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Limitations 


1.1. Overview 



Introduction 


This document describes the Pixrect graphics library, a set of routines that mani¬ 
pulate rectangular arrays of pixel values, on screen or in memory. These routines, 
called RasterOps, are common to all Sun woricstations. With these routines, 
application programs can manipulate the bit-mapped display on any Sun Works¬ 
tation. 

From a software perspective, the Pixrect graphics library is a low-level graphics 
package, sitting on top of the display device drivers. For most applications, the 
higher-level abstractions available in SunView and the Sun graphic standards 
libraries are more appropriate. For more information on these other packages, 
see the preface of this manual for references. 

The Pixrect library is intended only for accessing and manipulating two- 
dimensional, rectangular regions of a display device in a device-independent 
fashion. 

Windows 

The Pixrect library does not support overlapping windows. These can be 
implemented with memory pixrects by the application, but the SunView 
package already offers a sophisticated, easy-to-use programming interface 
for this purpose. 

Input Devices 

The Pixrect library does not have input functions. An application can use 
the input functions available in SunView, or make system calls directly to the 
raw input devices (see mouse(4) and kbd(4)). 

This manual is divided into chapters that describe the major features of the Pix¬ 
rect library. This chapter provides an introduction to the Pixrect library, defining 
important terms and concepts, and describing the resources available to the pro¬ 
grammer. Chapter 2 explains how to write Pixrect programs that can run on all 
Sun systems. Chapter 3 covers the operations for opening and manipulating pix¬ 
rects. Chapter 4 describes the text facilities in the Pixrect library. Chapter 5 
discusses memory pixrects, rectangular regions of virtual memory that are mani¬ 
pulated as pixrects. Chapter 6 explains the file HO functions in the Pixrect 
library. These functions can be used to store and retrieve pixrects from disk files. 
Appendix A is a implementation guide for writing pixrect device drivers. 
Appendix B is a list of the functions and macros in the Pixrect library. Appendix 
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1.2. Important Concepts 


0- X 



C is a list of types and structures in the Pixrect library. Appendix D describes 
the curve facilities in Pixrect. 

This section describes some of the important concepts behind the Pixrect library. 
It is not intended to be complete but rather to explain some features of the Pixrect 
library that make it unique among graphics packages. 


Screen Coordinates 

The screen coordinate system is two dimensional; the origin is in the upper 
left comer, with x and y increasing to the right and down. Th^ coordinates 
describing pixel locations in a pixrect are integers ranging from 0 to the 
pixrect’s width (for x) or height (for y) minus 1. The maximum value for x 
and y is 32767. 


Pixels 

A pixel is the smallest individual picture element that can be displayed on 
the screen. A pixel has an address (corresponding to an x and y coordinate) 
used to specify it, and a value, which controls the color displayed. The pixel 
address can be absolute (its screen coordinate) or relative to some rectangu¬ 
lar sub-region of the screen. A pixel has a depth (the number of bits it con¬ 
tains) which determines the range of colors it can display. A single bit pixel 
can be only black or white, and are used in monochrome displays. Pixels 
with more bits can display grayscale values or color. The most common 
pixel depths are one, eight, sixteen, or twenty-four bits per pixel. 

Bimaps 

A bitmap is a rectangular region of screen space. Each pixel on the screen 
corresponds to some number of bits in the screen memory. The value of 
these bits determines the color of the corresponding pixel. These groups ate 
arranged in an array that can be accessed using the x and y coordinates of the 
corresponding pixel. A pixrect bitmap can be up to 32767 pixels wide, and 
up to 32767 pixels high. 



The word “bitmap” can describe the the type of display, indicating it uses 
raster (rather than vector) display technology, or mote commonly, to the 
images stored in bitmap format. Examples of the second type of bitmap 
include the screen image, window images, the cursor, or icons. 


RasterOps 

RasterOps are the legal operations available for modifying pixrects. A 
rasterop is an operation which takes two bitmaps as arguments: a source bit¬ 
map, and the current state of the destination bitmap. The RasterOp then per¬ 
forms a boolean operation using these argiunents, pixel by pixel, writing the 
final result to the destination bitmap. The source bitmap may be pattern, or 
defined as a region of some constant value. 

The pr_stencil () function is the only RasterOp that breaks this rule. 
Along with the source and destination bitmaps, this function takes an addi 
tional argument, a texture bitmap, and combines the three in a boolean 
operatioa See Chapter 3 for a more detailed explanation of the RasterOp 
functions available in the Pixrect graphics library. 
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Figure 1-1 RasterOp Function 
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Pixrects 

A pixrect is the graphics analogy to an instance of a class used in object- 
oriented programming languages. It consists of bitmap data and the opera¬ 
tions that can be performed on that data. The implementation of the opera¬ 
tions and the data itself is hidden from the programmer (the only exception 
is memory pixrects, whose bitmap data can be directly manipulated. See 
Chapter 5 for details.) The pixrect is manipulated by using one of the func¬ 
tions in the pixrect library valid for that pixrect (analogous to sending it a 
message m. object-oriented Programming.) 

A pixrect object can reside on a variety of devices; including different types of 
graphics displays, memory, and printers. Since the available operations are the 
same regardless of the device the pixrect resides in, the programmer can ignore 
device particularities while writing the application. 

1.3. Using Pixrects The general procedure for drawing pictures using pixrects takes three steps: 

1 . Open a pixrect object. 

2. Draw a picture into the pixrect, using the set of valid operations: 

pr_put() 
pr_vector() 
pr_rop() 

' etc. 

3. Close the pixrect. 

Primary Pixrect If the pixrect resides on a display device, the result of each drawing operation 

becomes visible immediately. Opening a display pixrect will not erase the previ¬ 
ous contents of the display. Closing the pixrect also has no effect on the contents 
of the display. 
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Secondary Pixrect 


Memory Pixrect 


Basic Example 


Compiling 


A secondary pixrect is a proper subset of its parent pixrect. The results of draw- 
ing operations to a secondary pixrect are displayed immediately, if the parent’s 
pixrect is visible. A secondary pixrect can simplify programming, by allowing 
the programmer to isolate a section of a larger pixrect, sending drawing com¬ 
mands relative to that pixrect, rather than to its parent Pixrects can be nested to 
any depth. 

A memory pixrect allocates a section of memory in the workstation. Unlike a 
primary or secondary pixrect a memory pixrect does clear its bitmap to zeros 
when opened. Operations done on memory pixrects don’t show on the screen. 

An image in a memory pixrect can be copied to a display pixrect, allowing a sim¬ 
ple form of double buffering. A memory pixrect can also be used a buffer or 
scratch pad, storing bitmaps for later use, or to save the results of previous opera¬ 
tions. 

The following example draws a diagonal line near the upper comer of the 
woikstation’s default display. 

Figure 1-2 Basic Example Program 


o 

W' 


-^^ 

#includ.e <pixrect/pixrect_hs .h> 

main() 

{ 

Pixrect *screen; 

screen = pr_open("/dev/fb”); 

pr_vector(screen^ 10, 20, 70, 80, PIX_SET, 1); 
pr_close(screen); 

} 

^_ J 


The header file <pixrect/pixrect_hs . h> #includes all of the header 
files necessary for working with the functions, macros and data structures in the 
Pixrect library. 

The example program can be compiled as follows: 
examp le % cc riiniB, d - o line - Ipixrect 


This command line compiles the program in line. c. The -Ipixrect option 
causes the C compiler to link the Pixrect library to the application program and 
create an executable file named line. 


The sample program can be executed by the SunOS C-shell: 



A diagonal line will appear in the upper left hand comer of the screen. 
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Pixrect lint Library 


1.4. Pixrect Data 
Structures 


Pixrect provides a lint(l) library, which allows lint to check your program 
beyond the capabilities of the C compiler. Using the -Ipixrect flag provides 
lint with pixiect-specific information that prevents bogus error messages. You 
could use lint to check a program called box. c with command like this: 


Note that most of the error messages generated by lint are warnings, and may 
not necessarily have any effect on the operation of the program. For a detailed 
explanation of lint, see the discussion on lint in the C Programmer’s Guide 
manual. 

All of the important Pixrect data structures are stored in the header files shown in 
the table below. They can be found in the /usr/ include/pixrect direc¬ 
tory. Use these files to look up the exact definition of a function or macro you’re 
not sure about. 


e2^ample% lint: box.c -Ipixrect 


Table 1-1 Pixrect Header Files 


pixrect_hs .h 

♦includes all pixrect files 

pixrect.h 

most pixrect definitions 

memvar.h 

memory pixrects 

pixfont.h 

text operations 

traprop.h 

traprop definitions 

praline. h 

defines wide and textured vectors 

pr__planegroups .h 

frame buffers 

pr util 

internal definitions 
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Portability Considerations 


This chapter addresses Pixrect portability between different Sun architectures. 
Since Pixrects is a low-level graphics library, it is not completely device 
independent. Currently, the only Sun architecture that brings up porting issues is 
Sun386i, the first Sun system to use the Intel 80386 processor. The pixrect 
software has been designed to minimize porting difficulties; nevertheless, there 
are some portability factors to take into consideration. 

The sections below describe the portability problems caused by the Sun386i sys¬ 
tem, and their solutions. 

The 80386,68020, and SPARC are 32-bit processors. This means that all data read 
or written by these processors pass through 32-bit wide registers. The order in 
which the data — the b)d:es and bits — are arranged in the 80386’s registers 
differs from the 680X0 and SPARC families. These differences are illustrated in 
the figure below: 

Figure 2-1 Byte and Bit Ordering in the 80386,680X0 and SPARC 

80386 

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 1211 10 09 08 07 06 05 0403 02 0100 


Byte n+3 Byte n+2 

Byte n+1 Byte n 

Word n+1 

Word n 

Doubleword n 


2.1. Byte Ordering 



680X0 and SPARC 

313029 28 27 2625 24 23 22 2120 191817 16 151413 1211 1009 08 07 0605 0403 020100 


Byte n Byte n+1 

Byte n+2 Byte n+3 

Word n 

Word n+1 

Longword n 


Byte Swapping and Bit 
Flipping 



The Sun386i is based on the 80386 processor, which handles bjde ordering dif¬ 
ferently than 680X0 and SPARC processors. This affects the Sun386i’s interpreta¬ 
tion of graphics files — font files, icon files, cursor files, and screendumps — 
generated by the other two architectures. Typically, frame buffers are accessed 
as if they were word (i.e., 16-bit integer) devices, or as an array of words. 
Because the byte ordering of words is different on the two architectures. 
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transferring a graphics file from one to the other will usually result in a garbled 
picture. 

On 680X0 monochrome frame buffer, the bits are shifted out of the word starting 
at the most significant bit, bit 15. The upper left-most pixel on the screen is bit 
15, Word 0 of the frame buffer memory. The next pixel, scanning from left to 
right as you view the screen, is bit 14. The pixel to the right of the first 16 pixels 
displayed comes from word 1, bit 15. When interpreted as integers, the most 
significant and least significant bytes are: 

680X0 



MSB 

LSB 

wordO 

151413 1211 10 9 8 

76543210 

word 1 

151413 1211 10 9 8 

76543210 




wordn 

151413 1211 10 9 8 

76543210 


For example, the integer (word) value 0x37 OD in word 0 would show up on the 
680X0 and SPARC monochrome frame buffer as the pixel sequence: 


□□■■□■■■□□□□■■□a. 


On the 80386 monochrome frame buffer, the bits are shifted out of the word from 


the least significant bit, bit 0, 

80: 

LSB 

to the most, bit 15: 

186 

MSB 

wordO 

01234567 

8 91011 1213 14 15 

word 1 

01234567 

8 91011 1213 1415 


wordn 0 1 2 3 4 5 6 7 8 9 1011 1213 1415 


For example, the integer (word) value 0x37 OD in word 0 would show up on the 
screen with the 80386 frame buffer as the pixel sequence: 

anaarmnaaanaam. 

The bytes are backward and the bits are in the opposite order. Because graphics 
files are usually generated as an array of words, the bytes are backward for a typi¬ 
cal 80386 frame buffer when handling files generated by 680X0 and SPARC 
machines. Eight-bit color frame buffers represent each pixel as a b 3 de of data, so 
the bit order is already correct; conversion only requires byte swapping. 

For monochrome frame buffers, each pixel is represented by a single bit; scan¬ 
ning from right to left presents a bit flip and byte swap problem. The right-most 
(low-order) bit of a bit field now represents the left-most pixel on the screen. 

Because of the large number of existing files using it, the 680X0/SPARC format is 
the standard format for describing graphics images on all Sun systems. This 
eliminates the need for two sets of files in a mixed-architecture network. Conse¬ 
quently, if you are porting programs to the Sun386i from other Sun systems — 
programs that access the frame buffer through SunView and Pixrect —byte and 
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bit ordering is handled automatically at run time. The 680X0/SPARC format 
images are converted to 80386 format 

2.2. Flipping Pixrects Sun386i systems convert 680X0/SPARC format images into 80386 format just 

before they are used. The procedure that converts them is a new Pixrect routine, 
pr_f lip (), found only in the Sun386i version of Pixrect. 


The internal data of a pixrect is referenced by its pr_data field. 



If its a memory pixrect, the stmcture referenced by pr_dat a is: 


r 

^ 

Struct mpr_data 

1 

int 

md_l inebyt e s; 

short 

*md_image; 

struct 

pr_j)os md_offset; 

short 

md_p r ima r y ; 

short 

md_flags; /*flag bits*/ 

}; 


V 

----> 


There are two new flag bits in the md_f lags word, to control the operation of 
pr_flip(). The flags MP_REVERSEVIDEO,MP_DISPLAY, and 
MP_planemask are now followed by MP_I386 and MP_STATIC. If true, 
MP_I38 6 indicates that the pixrect in question is already in Sun386i ( 80386) 
display format, i.e., it has already been modified by pr f lip (). If 
MP STATIC is true, the pixrect in question is a static pixrect. (In practice, this 
flag is sometimes set for other purposes as well.) 

The pr_flip() Routine Thepr_flip() routine operates on individual pixrects. It takes one argument, 

a pointer to a pixrect stmcture, and returns void. When called, it first checks to 
see if the pixrect has already been flipped ( MP_I3 8 6 == TRUE). If not, it flips 
the image area, 16 bits at a time. First the bit order is reversed, then the b 5 l:es are 
swapped. It will not flip a display pixrect or a secondary pixrect imless it is static 
( MP_STATIC == TRUE). 

When a pixrect is modified by a pr_f lip () call, the changes are limited to the 
pixrect’s image area and the state of the two new md_f lags. The size of the 
pixrect stmctures remains unaltered. The new md_f lags are ignored by pro¬ 
grams mnning under 680X0 or SPARC. 

Pixrects are flipped as they are manipulated by any of the Pixrect routines listed 
below. As an application runs, the rate of pixrect flipping usually declines, since 
most applications develop a "working set" of active pixrects. Pixrects that are 
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not used are not flipped. 

The routines listed contain checkpoints, where pixrects used in the routines’ 
arguments are examined and flipped (if necessary) by pr_f lip (); 




Table 2-1 


NOTE 


Routines that call pr_f lip { ) 

mem_rop() 
mem_create() 
pr_region() 
pr_vector() 
pr_diainp_init () 
pf_open() 
pf_open_private() 
pr_stencil() 
pr_batchrop() 
pr_replrop() 
pr_get() 
pr_put() 
pr_load() 
pr_dump{) 

icon_display() 

DEFINE ICON FROM IMAGE 


Icons are either static or created with icon_load (). Static icons can be 
created with DEFINE_ICON_FROM_IMAGE Both of these Sunview features are 
described in the SunView 1 Programmer’s Guide. 



Fonts are converted by the pf_open () or pf_open_private () routines. 
No other conversions are allowed. The libraries work only with the existing 
standard font files. 


Guidelines for Sun386i 
Systems 


1. Check code that draws manually into a pixrect. It may not work properly on 
a Sun386i without modification. The modification required depends on the 
particulars of the drawing operation. 

2. Manual operations (not involving libpixrect routines) should be per¬ 
formed on a pixrect before converting it to 80386 format. 

3. inem_create 0 creates an 80386-foimat pixrect on Sun386i machines. 

4. mem_j)oint does not set the MP_I38 6 flag. The pixrect is still marked 
not flipped. 


5. To create an icon, use mem_point () to make a pixrect cormected to an 
existing static image or an image that you have created dynamically. 


6. Use DEFINE_IC0N_FR0M_IMAGE (SunView) to create static icons. All 
static icons are initially created in 680X0/SPARC format. They are converted 
to 80386 format when they are involved in a raster operation. 
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Pixrect Operations 


Rxrect objects contain procedures to perform the following operations: 

o create or destroy a pixrect (pr_open (), pr_region () and 
pr_destroy ()). 

□ read and write the values of single pixels within a pixrect (pr_get and 

pr_j5ut ()). 

□ use RasterOp functions to simultaneously affect multiple pixels within a pix¬ 
rect: 


pr_rop write from a source pixrect to a destination pixrect, 

pr stencil write from a source pixrect to a destination pixrect through 
a mask pixrect, 

pr_replrop replicate a constant source pixrect pattern throughout a des¬ 
tination pixrect, 

pr_batchrop 

write a batch of source pixrects to a sequence of locations 
within a single destination pixrect, 

pr_vector, pr_line 

draw a straight line in a pixrect, 

pr_polygon_2 

draw a polygon in a pixrect 

□ draw text (described in chapter 4, Text Facilities for Pixrects). 

□ read write the display’s colormap (pr_getcolormap {), 
pr j>utcolormap () ) 

□ select particular bit-planes in a color pixrect’s bitmap for manipulation 
(pr_getattributes(), prj)utattributes{)) 

□ control hardware double-buffering ( pr_dbl_get () and 
pr_dbl_set ()). 


From an object-oriented viewpoint, all pixrects contain both data and procedures 
to manipulate its data. This allows pixrects to be device-independent; the pixrect 
uses the function appropriate for its environment when asked to perform an 
operation. 
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From the programmers point of view, pixrects are manipulated using procedure 
calls embedded in application program. Internally, the pixrect procedures that 
act the same for aU pixrects are implemented by a single procedure for efficiency. 
The device-dependent calls are macros that access the appropriate procedure 
within the pixrect object. This is roughly equivalent to passing the pixrect object 
a message, which causes the pixrect to invoke the appropriate method (pro¬ 
cedure). 

Each pixrect object includes an internal pointer to a pixrect ops structure, that 
holds the addresses of the particular device-dependent procedures appropriate to 
that pixrect. Qients may access these procedures in a device-independent 
fashion, by calling the procedure through the pixrectops structure, rather 
than executing the procedure directly. To simplify this indirection, the Pixrect 
library provides a set of macros which look like simple procedure calls to generic 
operations, which expand to invocations of the corresponding procedure in the 
pixrectops stracture. 

In this manual, the description of each operation will specify whether it is a trae 
procedure or a macro, since some of the arguments to macros are expanded mul¬ 
tiple times, and could cause errors if the arguments contain expressions with side 
effects. (In fact, there are two sets of parallel macros, which differ only in how 
their arguments use the geometry data stmctures.) 


3.1. The pixrectops 

Structure 



The pixrectops stmcture is a collection of pointers to the device-dependent 
procedures for a particular device. AU other operations are implemented by 
device-independent procedures. From the object oriented view, this structure 
provides the procedural interface to the pixrect object translating messages to 
methods. This stmcture is designed .to aUow expansion; additional fimctions 
may be added in future releases. 
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A Pixrect procedure normally expects a number of arguments. These arguments 
can include: a pointer to the pixrect being manipulated, the dimensions and offset 
of a subregion within a pixrect, an ops argument describing the operation to be 
performed, among others. This section describes these arguments in detail, and 
the results returned by the pixrect procedure. 

In this manual, the conventions listed in Table 3-1 are used in naming the argu¬ 
ments to pixrect operations. 


Argument Name Conventions 


Argument 

Meaning 

dsuffix 

ssuffix 

prefixx 

prefix^ 

prefixw 

prefixh. 

destination 

source 

offset to left edge of pixrect 
offset to top edge of pixrect 
width of pixrect (0 to 32767) 
height of pixrect (0 to 32767) 


The X and y values given to functions that operate on a pixrect must be within 
the boundaries of that pixrect, and be in the range 0 to 32767. 

Pixrect Errors Pixrect operations indicate an error condition in one of two ways, depending on 

the t)^ of value the operation normally returns. Pixrect operations which return 
a pointer to a structure return NULL when they fail. For pixrect that return an 
integer status code, a return value of PIX_ERR (-1) indicates failure, while 0 
indicates the procedure completed successfully. The section describing each pix¬ 
rect procedure makes note of any exceptions to this convention. 

3.3. The Op Argument The multi-pixel operations described in the next section all use a uniform 

mechanism for specifying the operation which is to produce destination pixel 
values. This operation is given in the op argument and includes several com¬ 
ponents: 

□ A single constant source value may be specified as a color in bits 5 - 31 of 
the op argument. 

□ A RasterOp function is specified in bits 1 - 4 of the op argument. 

□ The clipping which is normally performed by every pixrect operation may 
be turned off by setting the PlX_DONTCLIP flag (bit 0) in the op. 

Figure 3-1 Structure of an op Argument 
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3.2. Callings Pixrect 
Procedures 

Argument Conventions 

Table 3-1 
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Specifying a RasterOp 
Function 


Four bits of the opr are used to specify one of the 16 distinct logical functions 
which combine monochrome source and destination pixels to give a mono¬ 
chrome result. This encoding is generalized to pixels of arbitrary depth by speci¬ 
fying that the function is applied to corresponding bits of the pixels in parallel. 
Some functions are much more common than others; the most useful are 
identified in Table 3-2. 



A convenient and intelligible form of encoding the function into four bits is sup¬ 
ported by the following definitions: 

- .. 

#define PIX_SRC 0x18 
#define PIX_DST 0x14 

fdefine PIX_NOT(op) (OxlE & ('(op))) 

V_^ J 


Pix_SRC and Pix_DST are defined constants, and Pix_NOT is a macro. 
Together, they allow the desired function to be specified by performing the 
corresponding logical operations on the appropriate constants. Note that 
PIX_N0T must be used in all RasterOp operations; the ones complement (~) 
operator will not work. 

A particular application of these logical operations allows definition of 
PIX_SET and PIX_CLR operations. The definition of the PIX_SET operation 
that follows is always tme, and hence sets the result: 


The definition of the Pix_CLR operation is always false, and hence clears the 
result: 



Other common RasterOp functions are defined in the following table: 


Table 3-2 Us^ul Combinations ofRasterOps 


Op with Value 

Result 

PIX_SRC 

PIX_DST 

PIX__SRC 1 PIX_DST 

PIX_SRC & PIX_DST 

PIX__NOT (PIX_SRC) & PIX DST 
PIX_NOT {PIX_DST) 

PIX_SRC ^ PIX__DST 

write same as source argument 

no-op same as destination argument 

peant OR of source and destination 

mask AND of source and destination 

erase and destination with source negation 

invert area negate the existing values 

inverting paint XOR of source and destination 


r - 


A 

#define PIX_SET (PIX_SRC 

PIX_NOT(PIX_SRC)) 


— .- -. 




o 
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Specifying a Color 


Controlling Clipping in a 
RasterOp 


Examples of Complete Op 
Argument Specification 
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A single color value can be encoded in bits 5-31 of the op argument 
ing macro supports this encoding: 

The follow- 

r 

#define PIX_COLOR(color) ((color) « 5) 

_ 

-N 

j 

Another macro extracts the color field from an encoded op: 

r 

fdefine PIX_OPCOLOR(op) ((op) » 5) 

- \ 

V 

J 


Note that the color is not part of the function component of the op argument and 
should never be part of an argument to PIX_NOT. 

The specified color is used by pixrect functions in two situations: 

1. If the source pixrect argument is NULL, the rasterop source operand is taken 
to an infinite rectangle of pixels with the specified color. 

2. If the source pixrect has a depth of 1 bit and the destination pixrect has a 
greater depth, the rasterop source operand is the specified color for each "1" 
source pixel and zero for each "0" source pixel. A color of zero is treated as 
a special case; it is converted to the maximum pixel value for the destination 
pixrect. 

If the destination pixrect has a depth of 1 bit, any nonzero color value is treated 
as 1; for other depths less significant bits of the color value are used. If the desti¬ 
nation pixrect is 32 bits deep the encoded color is sign extended. 

Pixrect operations normally clip to the bounds of the operand pixrects. Some¬ 
times this can be done more efficiently by the client at a higher level. If the 
client can guarantee that only pixels which ought to be visible will be written, it 
may instmct the pixrect operation to b)^ass clipping checks, thus speeding its 

operation. This is done by setting the following flag in the op argument: 

-^^ 

fdefine PIX DONTCLIP 0x1 


The result of a pixrect operation is undefined and may cause a memory fault if 
P IX_D0NTCL IP is set and the operation goes out of bounds. 

Note that the PIX_D0NTCLIP flag is not part of the function component of 
an op argument; it should never be part of an argument to PIX_NOT. 

A very simple op argument will specify that source pixels be written to a desti¬ 
nation, clipping to both operands: 


op = PIX_SRC; 


A more complicated example could be used to flip the color of destination pixels 
between two values wherever pixels in a 1 bit source pixrect are set, with clip¬ 
ping disabled for maximum performance: 
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/ 



op = (PIX_DST " PIX_SRC) 

1 PIX_COLOR(colorl " color2) \ 


1 PIX_DONTCLIP; 



^ .- 


J 


3.4. Creation and Pixrects are created by the procedures pr_open () and mem_create (), by 

Destruction of Pixrects the procedures accessed by the macro pr_region (), and at compile-time by 

the macro mpr_static ( ). Pixrects are destroyed by the procedures accessed 
by the macros pr_destroy () and pr_close (). mem_create () and 
mpr_st at ic {) are discussed in Chapter 5; the rest of these are described here. 


Create a Primary Display 
Pixrect 


Getting Screen Parameters 


Pixrect *pr_open(devicename) 
char *devicename; 

The properties of a non-memory pixrect depend on an underlying UNIX device. 

Thus, when creating the first pixrect for a device you need to open it by a call to 
pr_open () . The default device name for your display is / dev/ f b (f b stands 
for frame buffer). Any other device name may be used provided that it is a 
display device, the kernel is configured for it, it exists in the / dev directory, and 
it has pixrect support. For example; /dev/bwoneO, /dev/bwtwoO, 

/dev/cgoneO or /dev/cgtwoO all can exist on a Sun Woikstation, and can 
be opened with pixrects. 

pr_open ( ) does not work for creating a pixrect whose pixels are stored in 
memory; that function is served by the procedure meiti_create () , discussed in 
Chapter 5. 

pr_open () returns a pointer to a primary Pixrect structure which covers the 
entire surface of the named device. If it cannot, it returns NULL, and prints a 
message on the standard error output. 

In order to write portable programs, it is important to read the screen characteris¬ 
tics directly, rather than assuming them. The pixrect returned by pr_open () ^ 

contains this information. The two most important values are the dimensions of 
the screen, and the depth (number of bits) of each pixel. The code sample below 
opens a screen pixrect, then extracts the width, height and depth (in bits) of the 
screen. 
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/ ---—- 

tinclude <pixrect/pixrect hs.h> 
tinclude <stdio.h> 

main() 

Pixrect ^screen, *pr_open(); 
int height, width, depth; 

include the proper definitions 


screen points to screen pixrect 
variables to make things clearer 


screen = pr_open("/dev/fb"); 

open the pixrect 


width = screen->pr size.x; 
height = screen->pr_size.y; 
depth = screen->pr depth; 

extract the data in pr size; 
width and height are in pixels 
get depth in bits 


(void)printf("width = %d, height = %d, bits/pixel = %d0, 
width, height, depth) ; display result 


(void)pr close(screen); 

) 

close the pixrect 

j 


Create Secondary Pixrect #define Pixrect *pr_region (pr, x, y, w, h) 

Pixrect *pr; 
int X, y, h; 

#define Pixrect *prs_region(subreg) 
struct pr_subregion subreg; 

Given an existing pixrect, it is possible to create another pixrect which refers to 
some or all of the pixels in the parent pixrect. This secondary pixrect is created 
by a call to the procedures invoked by the macros pr_region () and 
prs_region {). 

The existing pixrect is addressed by pr; it may be a pixrect created by 
P3^_open (), inem_create () orinpr_static () (a primary pixrect); or it 

may be another secondary pixrect created by a previous call to a region opera¬ 
tion. The rectangle to be included in the new pixrect is described by X, y, w and 

h in the existing pixrect; (x , y) in the existing pixrect wDl map to (0,0) in the 
new one. prs_region() does the same thing, but has all its argument values 
collected into the single stmcture subreg. Each region procedure returns a 
pointer to the new pixrect. If it fails, it returns NULL. 

If an existing secondary pixrect is provided in the call to the region operation, the 
result is another secondary pixrect referring to the underlying primary pixrect; 

there is no further connection between the two secondary pixrects. Generally, the 

distinction between primary and secondary pixrects is not important; however, 
no secondary pixrect should ever be used after its primary pixrect is destroyed. 
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Release Pixrect Resources 


3-5. Single-Pixel 
Operations 
Get Pixel Value 


Set Pixel Value 


#define pr_close(pr) 
Pixrect *pr; 


#define pr_destroy(pr) 
Pixrect *pr; 



#define prs_destroy(pr) 

Pixrect *pr; 

The macros pr_close 0, pr_destroy () and prs_destroy () invoke 
device-dependent procedures to destroy a pixrect, freeing resources that belong 
to it. The procedure returns 0 if successful, P IX_ERR if it fails. It may be 
applied to either primary or secondary pixrects. If a primary pixrect is destroyed 
before secondary pixrects which refer to its pixels, those secondary pixrects are 
invalidated; attempting any operation but pr_destroy () on them is an error. 
The three macros are identical; they are all defined for reasons of history and 
stylistic consistency. 


The next two operations manipulate the value of a single pixel. 


#define pr_get(pr, x, y) 
Pixrect *pr; 
int X, y; 


#define prs__get (srcprpos) 
struct prj>rpos srcprpos; 



The macros pr get and pr s__get invoke device-dependent procedures to 
retrieve the value of a single pixel, pr indicates the pixrect in which the pixel is 
to be found; x and y are the coordinates of the pixel. For pr s_get, the same 
arguments are provided in the single struct srcprpos. The value of the pixel is 
returned as a 32-bit integer; if the procedure fails, it returns PIX_ERR. 


fdefine prj>ut (pr, x, y, value) 

Pixrect *pr; 
int X, y, value; 

#define prs_put(dstprpos, value) 
struct pr_prpos dstprpos; 
int value; 

The macros pr_put () and pr s_put () invoke device-dependent procedures 
to store a value in a single pixel, pr indicates the pixrect in which the pixel is to 
be found; x and y are the coordinates of the pixel. For pr s_jput (), the same 
arguments are provided in the single struct dstprpos. value is truncated on 
the left if necessary, and stored in the indicated pixel. If the procedure fails, it 
returns FIX ERR. 


w 
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3,6. Multi-Pixel Operations The following operations all apply to multiple pixels at one time: pr rop (), 

pr_stencil(), pr_replrop{),pr_batchrop (),pr_j>olYgon_ 2 (), 
and pr_vector 0 . With the exceptions of pr_vector () and 
pr_j>olYgon _2 {), they refer to rectangular areas of pixels. They all use a 
common mechanism, the op argument described in the previous section, to 
specify how pixels are to be set in the destination. Appendix D. describes the 
pr_traprop () curve rendering function. 

#def.ine pr_rop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 
int dx, dy, dw, dh, op, sx, sy; 

♦define prs_rop(dstregion, op, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr_prpos srcprpos; 

Thepr_rop() andprs_rop() macros invoke device-dependent procedures 
that perform the indicated raster operation from a source to a destination pixtecL 
dpr addresses the destination pixrect, whose pixels will be affected; (dx, dy) is 
the origin (the upper-left pixel) of the affected rectangle; dw and dh are the 
width and height of that rectangle, spr specifies the source pixrect, and 
(sx, sy) an origin within it spr may be NULL, to indicate a constant source 
specified in the op argument, as described previously; in this case sx and sy are 
ignored. The op argument specifies the operation which is performed; its con- 
stmction is described in preceding sections. 

() is the only pixrect function that can have its source and destination 
be overlapping areas of the same pixrect. Doing this with any other operation 
generates an error. 

For prs_rop (), the dpr, dx, dy, dw and dh arguments are aU collected in a 
pr_subregion structure. 

Raster operations are clipped to the source dimensions, if those are smaller than 
the destination size given. pr_rop() procedures return PIX_ERR if they fail, 
0 if they succeed. 

Source and destination pixrects generally must be the same depth. Tte only 
exception allows monochrome pixrects to be sources to a destination of any 
depth. In this case, source pixels = 0 are interpreted as 0 and source pixels = 1 
are written as the color value from the op argument. If the color valiK in the op 
argument is 0 , source pixels = 1 are written as the maximum value which can be 
stored in a destination pixel. 

See the example program in Figure 5-2 for an illustration of pr_rop (). 

RasterOps through a Mask 



RasterOp Source to 
Destination 
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I 
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#define pr__stencil (dpr^ dx^ dy^ dw^ dh^ op^ 
stpr, stx, sty, spr, sx, sy) 

Pixrect *dpr, *stpr, *spr; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 



Replicating the Source Pixrect 


#define prs_stencil(dstregion, op, stenprpos, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr_prpos stenprpos, srcprpos; 


The pr_stencil and pr s_stencil macros invoke device-dependent pro¬ 
cedures that perform the indicated raster operation from a source to a destination 
pixrect only in areas specified by a third (stencil) pixrect. pr_stencil() is 
identical to pr rop {) except that the source pixrect is written through a stencil 
pixrect which functions as a spatial write-enable mask. The stencil pixrect must 
be a monochrome memory pixrect. The indicated raster operation is applied only 
to destination pixels where the stencil pixrect is non-zero. Other destination pix¬ 
els remain unchanged. The rectangle from (sx, sy) in the source pixrect spr is 
aligned with the rectangle from (stx, sty) in the stencil pixrect stpr, and 
written to the rectangle at (dx, dy) with width dw and height dh in the destina¬ 
tion pixrect dpr. The source pixrect spr may be NULL, in which case the color 
specified in op is painted through the stencil. Clipping restricts painting to the 
intersection of the destination, stencil and source rectangles. pr_stencil () 
procedures return PIX ERR if they fail, 0 if they succeed. 

pr_replrop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 



#define prs_replrop(dsubreg, op, sprpos) 
struct pr_subregion dsubreg; 
struct pr_prpos sprpos; 

Often the source for a raster operation consists of a pattern that is used repeat¬ 
edly, or replicated to cover an area. If a single value is to be written to all pixels 
in the destination, the best way is to specify that value in the color component 
of a pr_rop () operation. But when the pattern is larger than a single pixel, a 
mechanism is needed for specifying the basic pattern, and how it is to be laid 
down repeatedly on the destination. 

The pr_replrop () procedure replicates a source pattern repeatedly to cover a 
destination area, dpr indicates the destination pixrect. The area affected is 
described by the rectangle defined by dx, dy, dw, dh. spr indicates the source 
pixrect, and the origin within it is given by ( sx, sy). The corresponding 
prs_replrop () macro generates a call to pr_replrop (), expanding its 
dsubreg into the five destination arguments, and sprpos into the three source 
arguments, op specifies the operation to be performed, as described above in 
Section 3.3, The Op Argument. 

The effect of pr_replrop () is the same as though an infinite pixrect were 
constructed using copies of the source pixrect laid immediately adjacent to each 
other in both dimensions, and then a pr_rop () was performed from that source 
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to the destination. For instance, a standard gray pattern may be painted across a 
portion of the screen by constracting a pixrect that contains exactly one tile of the 
pattern, and by using it as the source pixrect. 

The alignment of the pattern on the destination is controlled by the source origin 
given by ( sx, sy). If these values are 0, then the pattern will have its origin 
aligned with the position in the destination given by ( dx, dy). Another common 
method of alignment preserves a global alignment with the destination, for 
instance, in order to repair a portion of a gray. In this case, the source pixel 
which should be aligned with the destination position is the one which has the 
same coordinates as that destination pixel, modulo the size of the source pixrect. 
pr replrop () will perform this modulus operation for its clients, so it 
suffices in this case to simply copy the destination position (dx, dy) into the 
source position (sx, sy). 

pr_replrop() returns P IX_ERR if it fails, or 0 if it succeeds. Internally 
pr_replrop {) may usepr_rop 0 procedures. In this case, pr_rop {) 
errors are detected and returned by pr_replrop (). 

IVIultiple Source to the Same #d.efine pr_^batchroptdpr, dx, dy, op, items, n) 

Destination Pixrect *dpr; 

int dx, dy, op, n; 
struct pr_prpos items!]; 

fdefine prs_batchrop(dstpos, op, items, n) 
struct pr_prpos dstpos; 
int op, n; 

struct pr_j)rpos items!]; 

Applications such as displaying text perform the same operation from a number 
of source pixrects to a single destination pixrect in a fashion that is atnenahle to 
global optimization. 

The pr_batchrop and prs_batchrop macros invoke device-dependent 
procedures that perform raster operations on a sequence of sources to successive 
locations in a common destination pixrect. items is an array of pr_j 5 rpos 
stmctures used by a pr_bat chrop () procedure as a sequence of source pix¬ 
rects. Each item in the array specifies a source pixrect and an advance in x and 
y. The whole of each source pixrect is used, unless it needs to be clipped to fit 
the destination pixrect. The advance is used to update the destination position, 
not as an origin in the source pixrect. 

pr bat chrop () procedures take a destination, specified by dpr, dx and dy, 
or by dstpos in the case of prs_bat chrop (); an operation specified in op, 
as described in Section 3.3. and an array of pr_jprpos addressed by the argu¬ 
ment it ems, and whose length is given in the argument n. 

The destination position is initialized to the position given by dx and dy. Then, 
for each item, the offsets given in pos are added to the previous destination 
position, and the operation specified by op is performed on the source pixrect 
and the corresponding rectangle whose origin is at the current destination posi¬ 
tion. Note that the destination position is updated for each item in the batch, and 
these adjustments are cumulative. 
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Draw Vector 


Draw Textured Polygon 


The most common application of pr_batchrop () procedures is in painting 
text; additional facilities to support this application are described in Chapter 4. 
Note that the definition of pr_batchrop () procedures supports variable-pitch 
and rotated fonts, and non-Roman writing systems, as well as simpler text 



pr_bat chrop {) procedures return P IX_ERR if they fail, 0 if they succeed. 
Internally pr_batchrop 0 may use pr_rop () procedures. In this case, 
pr_rop () errors are detected and returned by pr_bat chrop (). 


fdefine pr_vector(pr, xO, yO, xl, yl, op, value) 
Pixrect *pr; 

int xO, yO, xl, yl, op, value; 


idefine prs_vector(pr, posO, posl, op, value) 

Pixrect *pr; 

struct pr__pos posO, posl; 
int op, value; 

The pr_vector and prs_vector macros invoke device-dependent pro¬ 
cedures that draw a vector one unit wide between two points in the indicated pix¬ 
rect. pr_vector() procedures draw a vector in the pixrect indicated by pr, 
with endpoints at (xO , yO) and (xl, yl), or at posO and posl in the case of 
prs_vector (). Portions of the vector lying outside the pixrect are clipped as 
long as PIX_D0NTCLIP is 0 in the op argument. The op argument is con¬ 
structed as described in Section 3.3. and value specifies the resulting value of 
pixels in the vector. If the color in op is non-zero, it takes precedence over the w 
value argument. 

Any vector that is not vertical, horizontal or 45 degree will contain jaggies. This 
phenomenon, known as aliasing, is due to the digital nature of the bitmap screen. 

It can be visualized by imagining a vertical vector. Displace one endpoint hor¬ 
izontally by a single pixel. The resulting line will have to jog over a pixel at 
some point in the traversal to the other endpoint. Balancing the vector guaran¬ 
tees that the jog will occur in the middle of the vector. pr_vector() draws 
balanced vectors. (The technique used is to balance the Bresenham error term). 

The vectois are balanced according to their endpoints as given and not as 
clipped, so that the same pixels will be drawn regardless of how the vector is 
clipped. 

See the example program in Figure 1-2 for an illustration of pr_vector (). 


pr_polygon_2(dpr, dx, dy, nbnds, npts, vlist, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy 

int nbnds, npts[]; 

struct pr_pos *vlist; 

int op, sx, sy; 

The pr_polygon_2 () function performs a raster operation on a polygonal 
area of the destination pixrect. The source can be a pattern or a constant color 
value. 
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The destination polygon is described by nbnds, npts and vlist. nbnds is 
the number of individual closed boundaries (vertex lists) in the polygon. A com¬ 
plex polygon may have one boundary for its exterior shape and several boun¬ 
daries delimiting interior holes. The boimdaries may intersect themselves or 
each other. Only those destination pixels having an odd winding number are 
painted. That is, if any line cormecting a pixel to infinity crosses an odd number 
of boundary edges, the pixel will be painted. 

For each of the nbnds boundaries, npts specifies the number of points in the 
boundary. The vlist array contains the boundary points for all of the boun¬ 
daries, in order. The total number of points in vlist is equal to the sum of the 
nbnds elements in the npts array. pr_polygon_2 () automatically joins the 
last point and first point to close each boundary. If any boundary has fewer than 
3 points, pr_polygon_2 () returns P IX_ERR. 

The destination coordinates dx, and dy are added to each point in vlist, so the 
same vlist can be used to draw polygons in different destination locations. 

If the source pixrect spr is non-null, it is replicated in the x and y directions to 
cover the entire destination area. The point ( sx, sy) in this extended source 
pixrect is aligned with the point ( dx, dy) in the destination pixrect. 

Polygons drawn by pr^olygon_2 () are semi-open in the sense that on some 
of the edges, pixels are not drawn where a vector drawn with satne coordinates 
would go. The reason is to allow identical polygons (same size and orientation) 
to exactly tile the destination pixrect with no gaps and no overlaps. 

In Figure 3-3 the edges AB and HA are drawn, whereas edges BC and CD aren’t 
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Figure 3-2 Example Program using pr_j>olygon_2 () 


#include <pixrect/pixrect__hs .h> 

#define CENTERX(pr) ((pr)->pr_size.x / 2) 
#define NULLPR ((Pixrect *) 0) 

static struct pr_jpos 
/* 45 degrees */ 


vlistO[4] = { {0^ 

0}, 

{ 

71, 

-71}, 

{141, 

0}, { 71, 

71} }, 

/* 30 degrees */ 
vlistl[4] = { {0,^ 

0}, 

{ 

00 

-50}, 

{137, 

37}, { 50, 

87} }, 

/* 0 degrees */ 
vlist2[4] = { {0, 

0}, 

{100, 

0}, 

{100, 

100}, { 0, 

100} }, 

/* -30 degrees */ 
vlist3[4] - { {0, 

0}, 

{ 

00 

50}, 

{ 37, 

137}, {-50, 

87} }; 


main () 

{ 

Pixrect *pr; 

static int npts[l] = { 4 ); 

if (!(pr = pr_open(”/dev/fb”))) 
exit(1); 


pr_polygon_2(pr, CENTERX(pr), 
PIX_SET, NULLPR, 0, 0); 

100, 

1, 

npts. 

vlistO, 

pr_polygon_2(pr, CENTERX(pr), 
PIX_SET, NULLPR, 0, 0) ; 

300, 

1, 

npts. 

vlistl 

pr_polygon 2(pr, CENTERX(pr), 
PIX_SET, NULLPR, 0, 0); 

500, 

1, 

npts. 

vlist2 

pr_polygon_2(pr, CENTERX(pr), 
PIX_SET, NULLPR, 0, 0); 

700, 

1, 

npts. 

vlist3 


pr_close (pr) ; 
exit (0); 
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Figure 3-3 Four Polygons Drawnwith prj)olygon_2 () 



Draw Textured or Solid Lines fdefine pr_line(pr, xO, yO, xl, yi, brush, tex, op) 
with Width Pixrect *pr; 

int xO, yO, xl, yl; 
struct pr_brush *brush; 
struct pr_texture *tex; 
int op; 

praline macro draws a textured line based on the Bresenham line drawing 
algorithm, using a pen-up, pen-down approach. The programmer can define an 
pattern (of arbitrary length), or use a predefined default pattern (dash-dot, dotted, 
etc.). All pattern segments (and their corresponding offsets) can automatically 
adjust, according to the angle at which the line is drawa 


If the brush pointer is NULL, or if 
the width is 0 or 1, a single width 
vector is drawn. 


The line is drawn in the pixrect indicated by pr, with endpoints at (xO, y 0 ) 
and (xl, y 1). The brush field is a pointer to a stmcture of type prbrush 
which holds the width of the line segments to be rendered. The pr_brush 
structure is defined in the header file <pixrect/pr_line, h> as follows: 
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typedef struct pr_brush { 


int width; 


} Pr__brush; 

<___^- 

J 


If the t ex pointer is NULL, a solid vector is drawn. The t ex field is a pointer 
to a structure of type pr_texture. The pr_texture structure is defined in 
the header file <pixrect/pr_line. h> as follows (fields that begin with the 
prefix res_ are reserved for program internals, and are not user-definable): 


c 

A 

typedef struct pr_texture { 


short ^pattern; 


short offset; 


struct pr_textureceptions { 


unsigned startpoint : 


endpoint : 


balanced : 


givenpattern : 1,- 


res fat : If 


resj>oly: 1, 


res_mvlist : If 


res_right : If 


res__close : 1; 


} options; 


short res_polyoff; 


short res oldpatln; 


short res fatoff; 


} Pr texture; 


^^__——- 

-J 


pattern is a pointer to an array of short integers which contain the length of 
each segment in the pattern. The lengths are in units of pixels. If the line is 
drawn at an angle, the lengths drawn are automatically adjusted (if the given- 
pattern field set to 0) to correspond to the length of the pattern if a horizontal 
or vertical line was drawn. This array must be null-terminated. The first seg¬ 
ment of the pattern array is assumed to be pen-down, and following segments 
alternate. 

The addresses of the following predefined pattern arrays may be stored in the 
pattern field of the texture stmcture as well: 


— 


- —--—- - 

extern 

short 

pr^tex^dotted[]; 

extern 

short 

pr tex_dashed[3; 

extern 

short 

pr tex^dashdot[]; 

extern 

short 

pr_tex_dashdotdotted[]; 

extern 

short 

pr tex longdashed[]; 

V 


j 


The programmer-defined elements of the pattern array are not altered within 
the routine, allowing multiple calls using the same pattern, of f set is an 
integer offset into the pattern, specified in pixels. Since the first segment of the 
pattern array is assumed to be pen-down, you must specify an offset to 

Asun 
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Draw Textured or Solid 
Polylines with Width 



start on a pen-up segment, offset is adjusted according to the angle at which 
the line is drawn if the original pattern was adjusted (dependent upon the 
givenpattern bit, described later). Because of integer approximation, the 
adjusted offset could vary plus or minus one pixel from the exact adjusted 
offset. 

In the options bit fields, if start point is set, the first point is always drawn, 
and if endpoint is set, the last point is drawn; if these are not specified, the 
line will be drawn with no extra pixels set. The balanced bit field effectively 
centers the pattern within the line by computing an offset into the pattern. If the 
givenpattern bit is set, the pattern is drawn without tme length correction, at 
any angle; this increases performance. However, the pattern of radiating lines 
from a common center will form concentric squares instead of circles. If the 
givenpattern bit is not set, the segment length of each element of the pattern 
is adjusted according to the angle at which the line is drawn. The tme (angle- 
dependent) segment lengths are computed for one period of the pattern, using an 
incremental algorithm which approximates file formula: 

angle_pattern_length = given_pattern_length * cos (angle) 
where aU units are in pixels, and angle is measured from the positive jc-axis. 

Since the algorithm angle-corrects for one period of the pattern, the longer its 
period, the more exact the results are. 

The op argument specifies the raster operations used to produce destination pixel 
values and color. 


P^_polyfine(dpr, dx, dy, npts, ptlist, mvlist, brush, tex, op) 

Pixrect *dpr; 

int dx, dy, npts; 

struct pr_pos *ptlist; 

u_char *mvlist; 

struct pr_brush *brush; 

struct pr_texture *tex; 

int op; 

P^_J>olyline draws a polyline, or a series of disjoint polylines, using the 
features available in pr line. The polyline is drawn in the destination pixrect 
indicated by dpr, with dx and dy being the offset into the destination pixrect 
for vertices to be translated in x and y, respectively, npt s is the number of ver¬ 
tices in the polyline (which is always the number of lines plus 1). The ptlist 
field is an array of npts stmctures of type pr_pos (which hold vertices). The 
mvlist field is a pointer to an array of npts elements in which if any element 
after the first is non-zero, a segment is not drawn to that vertex. The first element 
of the mvlist array controls whether the polyline(s) are automatically closed; if 
set, each continuous polyline is closed. If disjoint polylines are not desired (no 
mvlist is specified), the constants. POLY_CLOSE and POLY_DONTCLOSE 
determine this behavior. poly_close and poly_dontclose are defined as 
follows: 


#define POLY_CLOSE ((u_char *) 1) 
fdefine POLY_DONTCLOSE ((u_char *) 0) 

V___ 
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Draw Multiple Points 


3.7, Colormap Access 


Get Colormap Entries 


\ 


The brush field is a pointer to a structure of type pr_brush, and the t ex field 
is a pointer to a structure of type pr_texture. If the tex pointer is nuU, a 
solid vector is drawn. If the brush structure is null, single-width vectors are 
drawn, op specifies the raster operations used to produce destination pixel 
values and color, brush and tex are described in detail under pr_line. 

pr_j5olypoint (dpr, dx^ dy, npts, ptlist,^ op) 

Pixrect *dpr; 
int dx,. dy^ npts; 
struct pr_j30S *ptlist; 
int op; 

The pr_polypoint routine draws an array of points on the screen under the 
control of the op argument. The array of points is drawn in the destination pix¬ 
rect dpr , with an offset specified by the arguments dx and dy. Npt s is the 
number of points to be rendered, and pt list is a pointer to an array of struc¬ 
tures of type pr_j>os, which hold the vertices for each point Color is encoded 
in the op argument Portions of the array outside the pixrect are clipped unless 
the PIX_D0NTCLIP flag is set in the op argument. 

A colormap is a table which translates a pixel value into 8-bit intensities in red, 
green, and blue. For a pixrect of depth n, the corresponding colormap will have 
2 ” entries. The two most common cases are monochrome (two entries) and color 
(256 entries). Memory pixrects do not have colormaps. 

Sun grayscale workstations noraiaUy use the red video signal to drive the moni¬ 
tor. However, when writing an application to run on a grayscale workstation it is 
a good idea to load the red, green, and blue components of each colormap entry 
with the same value. This will ensure that the application will also run properly 
on a color workstation. 

tdefine pr_getcolormap(pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count; 

unsigned char red[], green[], blue[]; 

tdefine prs_getcolormap(pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count; 

unsigned char red[], green[], blue[]; 

The macros pr_getcolormap and prs_get colormap invoke device¬ 
dependent procedures to read all or part of a colormap into arrays in memory. 

These two macros have identical definitions; both are defined to allow consistent 
use of one set of names for aU operations. 

pr identifies the pixrect whose colormap is to be read; the count entries start¬ 
ing at index (zero origin) are read into the three arrays. 

For monochrome pixrects the same value is read into corresponding elements of 
the red, green and blue arrays. These array elements will have their bits 
either aU cleared, indicating black, or all set, indicating white. By default. 
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Set Colormap Entries 


Inverted Video Pixrects 


the 0th (background) element is white, and the 1st (foreground) element is black. 
Colomiap procedures return (-1) if the index or count are out of bounds, and 0 if 
they succeed. 

fdefine pr_putcolormap(pr, index^ county red, green, blue) 

Pixrect *pr; 

int index, count; 

unsigned char red[], green[], blue[]; 

#define prs__putcolormap (pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count; 

unsigned char red[], green[], blue[]; 

The macros pr j>utcolormap and prs^putcolormap invoke device¬ 
dependent procedures to store from memory into aU or part of a colormap. These 
two macros have identical definitions; both are defined to allow consistent use of 
one set of names for all operations. The count elements starting at index 
(zero origin) in the colormap for the pixrect identified by pr are loaded from 
corresponding elements of the three arrays. For monochrome pixrects, the only 
value considered is red [ 0 ]. If this value is 0, then the pixrect wiU be set to a * , 
dark backgroimd and light foregroimd. If the value is non-zero, the foreground 
wiU be dark, e.g. black-on-white. Monochrome pixrects are dark-on-light by 
default. 

Note: FuU functionality of the colormap is not supported for monochrome pix¬ 
rects. Colormap changes to monochrome pixrects apply only to subsequent 
operations whereas a colormap change to a color device instantly changes all 
affected pixels on the display surface. 

pr_blackonwhite(pr, min, max) 

Pixrect *pr; 
int min, max; 

pr_whiteonblack(pr, min, max) 

Pixrect *pr; 
int min, max; 

pr_reversevideo(pr, min, max) 

Pixrect *pr; 
int min, max; 

Video inversion is accomplished by manipulation of the colormap of a pixrect. 

The colormap of a monochrome pixrect has two elements. The procedures 
P3^_t>lackonwhite, pr_whiteonblack and pr_reversevideo pro¬ 
vide video inversion controL These procedures are ignored for memory pixrects. 

In each procedure, pr identifies the pixrect to be affected; min is the lowest 
index in the colormap, specifying the background color, and max is the highest 
index, specifying the foreground color. These will most often be 0 and 1 for 
monochrome pixrects; the more general definitions allow colormap-sharing 
schemes. 
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“Black-on-white” means that zero (background) pixels wiU be painted at fidl 
intensity, which is usually white. pr_blackonwhite {) sets all bits in the 
entry for colormap location min and clears all bits in colormap location max. 



” White-on-black” means that zero (background) pixels wiU be painted at 
minimum intensity, which is usually black. pr_whiteonblack () clears aU 
bits in colormap location min and sets all bits in the entry for colormap location 
max. 

pr_r averse video () exchanges the min and max color intensities. 

Note: These procedures are intended for global foregroundAiackgroimd control, 
not for local hig hli g hti n g . For monochrome frame buffers, subsequent opera¬ 
tions will have inverted intensities. For color frame buffers, the colormap is 
modified immediately, which affects everything in the display. 


3.8. Attributes for Bitplane 
Control 


Get Plane Mask Attributes 


#define prs_getattributes(pr, planes) 

Pixrect *pr; 
int *planes; 

The macros pr_getattributes () and prs_getattributes () invoke 
device-dependent procedures that retrieve the mask which controls which planes 
in a pixrect are affected by other pixrect operations, pr identifies the pixrect; its 
current bitplanes mask is stored into the word addressed by planes. If 
planes is NULL, no operation is performed. 

The two macros are identically defined; both are provided to allow consistent use 
of the same style of names. 

Put Plane Mask Attributes idefine pr_putattributes (pr, planes) 

Pixrect *pr; 
int *planes; 


In a color pixrect, it is often useful to define bitplanes which may be manipulated 
independently; operations on one plane leave the other planes of an image unaf¬ 
fected. This is normally done by assigning a plane to a constant bit position in 
each pixel. Thus, the value of the bit in all the pixels defines the i*" bitplane 
in the image. It is sometimes beneficial to restrict pixrect operations to affect a 
subset of a pixrect’s bitplanes. This is done with a bitplane mask. A bitplane 
mask value is stored in the pixrect’s private data and may be accessed by the 
attribute operations. 


#define pr_getattributes(pr, 
Pixrect *pr; 
int *planes; 


planes) 


#define prsjiutattributes(pr, planes) 

Pixrect *pr; 
int *planes; 

The macros pr jjutattributes (), and pr s_putattributes () invoke 
device-dependent procedures that manipulate a mask which controls which 
planes in a pixrect are affected by other pixrect operations. The two macros are 
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identically defined; both are provided to allow consistent use of die same style of 
names. 

pr identifies the pixrect to be affected. The planes argument is a pointer to a 
bitplane write-enable mask. Only those planes corresponding to mask bits hav¬ 
ing a value of 1 will be affected by subsequent pixrect operations. If planes is 
NULL, no operation is performed. 

Note: If any planes are masked off by a call to pr_putattributes (), no 
further write access to those planes is possible imtil a subsequent call to 
pr_putattributes () unmasks them. However, these planes can still be 
read. 


3.9. Plane Groups A plane group is a subset of a frame buffer pixrect. Each plane group is a collec¬ 

tion of one or more related bit planes with stored state (plane mask, color map, 
etc.). Each pixrect has a current plane group which is the target of attribute, 
color map, and rendering operations. 


A plane group is described by a small constant in the header file 
<pixrect/pr_jplanegroups .h>: 


- --—-- 


A 

#define PIXPG CURRENT 

0 


#define PIXPG MONO 

1 


Mefine PIXPG_8BIT_COLOR 

2 


#define PIXPG_OVERLAy_ENABLE 

3 


#define PIXPG_OVERLAY 

4 




J 


Plane group 0 is the currently active plane group for the pixrect. 

A plane group is encoded as a 7-bit field in the pixrect attribute word. 


ngroups = pr__available j>lane_groups (pr^ maxgroups, groups); 

Pixrect *pr; 

int maxgroups; 

char groups[maxgroups] 

pr_available_plane_groups provides a means by which you determine 
which plane groups are supported by the machine you are working on. 
pr_available_plane_groups fills the character array groups with true 
(1) values for the plane groups implemented by the pixrect pr. The entry for the 
current plane groupj;groups [ 0 ]) array is always set to false (0). The size of 
groups is passed to the function as maxgroups to avoid overwriting the end 
of the array. 

pr_available_j3lane_groups returns the index of the highest-numbered 
implemented plane group plus one. 


Determine Supported Plane 
Groups 


Get Current Plane Group group |= pr_get^lane_group (pr) ; 

Pixreqt *pr; 

pr_get:_j)lane_group returns the current plane group number for the pixrect 
pr. If the current plane group is unknown, the function returns 
pixpgI current. 
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Set Plane Group and Mask 


3.10. Double Buffering 


Get Double Buffering 
Attributes 


void pr_set_plane_group(pr, group); 
Pixrect *pr; 
int group; 




void pr_set_planes (pr,. group, planes) 

Pixrect *pr; 
int group; 
int planes; 

pr_set_plane_group sets the current plane group for the pixrect pr to the 
value given by group. If this plane group is P IXPG_CURRENT or unimple¬ 
mented, pr_set j)lane_group does nothing. 

The pr_set_j)lanes function is equal to a pr_set_plane_group (pr, 
group) followed by pr_putattributes (pr, Splanes). planes 
contains a bitplane write-enable mask. Only those planes corresponding to mask 
bits having a value of 1 wiU be affected by subsequent pixrect operations. How¬ 
ever, the other planes can still be read. 


Some frame buffers have double buffering support implemented in hardware. 
Two pixrect commands, pr_dbl_get (), and pr_dbl_set () allow you to 
inquire about and control a double-buffered display device. The pixrect interface 
assigns two names to the buffers in the display; PR_dbl_A for one, and 
PR_DBL_B for the Other. 

A buffer can be displayed, read, or written. When a buffer is displayed, its 
stored image is shown on the screen. If the software requests that the other 
buffer be displayed, the hardware doesn’t switch to the new buffer until the next 
vertical retrace of the screen. This prevents any flicker from showing on the 
screen during the change between buffers. A buffer can be read or written, using 
pixrect commands, at any time. 



State == pr_dbl_get (pr, attribute) 

Pixrect *pr; 
int attribute; 

This function shows the current attributes of the double buffer. You can inquire 
about the state of the display device by executing pr_dbl_get with a particu¬ 
lar attribute value, then examining the function’s return value. The legal attri¬ 
butes are listed below: 


/- 

#define 

PR DBL AVAIL 

1 

\ 

#define 

PR DBL DISPLAY 

2 


#define 

PR_DBL_WRITE 

3 


#define 

PR_DBL__READ 

4 


V 





The PR_DBL_AVAIL returns PR_DBL_EXISTS if display device has hardware 
double buffering capacity; otherwise, it returns NULL. The other attributes indi¬ 
cate which buffer on the device is being displayed, which can be written to, etc. 
The possible state values for these attributes is given below: 
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#define 
♦define 
♦define 
♦define 


PR_DBL_A 2 
PR_DBL_B 3 
PR_DBL_BOTH 4 
PR DBL NONE 5 


Not all return values are possible with each attribute. The values that can be 
returned for a given attribute a shown in the table below; 


Table 3-3 pr_dbl_get () Attributes 


Attribute 

Possible Values Returned 

PR__DBL_AVAIL 

PR_DBL__DISPLAY 

PR_DBL__WRITE 

PR___DBL_READ 

PR_DBL_EXISTS 

PR_DBL_A, PR_DBL_B 

PR_DBL_A, PR_DBL_B, PR_DBL_BOTH, PR_DBL_NONE 
PR_DBL_A, PR_DBL_B 


Set Double Buffering 
Attributes 



void pr_dbl_set(pr, attribute_list) 

Pixrect *pr; 

int *attribute_list; 

The pr_dbl_set () function changes the state of the double buffering display. 
It controls the buffer being displayed, and selects the buffer(s) affected by pixrect 
reads and writes. The possible attributes for pr_dbl_set () are given below: 


- - 




#define 

PR DBL DISPLAY 

2 


#define 

PR DBL WRITE 

3 


#define 

PR_DBL_READ 

4 


tdefine 

PR_DBL_DISP LAY_DONTBLOCK 

5 





_/ 


An attribute list is an integer array consisting of pairs of attributes and the value 
the attribute should be set to. The last element of the array should be zero. If the 
display is already in the state requested, the function simply returns. 

If the PR_DBL_DISPLAY attribute is in the list, then the function may block for 
up to a single video frame’s time (15 ms), waiting for the next vertical retrace. 
This insures that the next pixrect operation won’t alter the buffer while it’s still 
being displayed. Applications that won’t write to the buffer for at least 15 ms 
after changing the displayed buffer, and who need maximum throughput can use 
PR_DBL_DISPLAY_DONTBLOCK. This attribute changes the display without 
blocking the process until the next vertical retrace. 

NOTE Programmers should use l?R_pBL_DlSP'LAY_DOmBljOCK with caution. If 
the application starts writing too early, it will modify the buffer while it is still 
being displayed. 

The values that can be paired with the attributes are shown below: 

L. ' 
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--— 

#define PR_DBL_A 2 
fdefine PR_DBL_B 3 
#define PR_DBL_BOTH 4 

__ y 



Not all of the values can be paired with aU of the attributes; the allowed pairings 
are shown in the table below: 


Table 3-4 pr_dbl_set () Attributes 


Attribute 

Possible Values to Set 

PR^DBLJWRITE 

PR_DBL__READ 

PR__DBL_DISPLAY_DONTBLOCK 

PR_DBL_DISPLAY 

PR_DBL_A, PR_DBL__B, PR_DBL^BOTH 
PR_DBL_A, PR_DBL_B 

PR_DBL_A, PR_DBL_B 

PR_DBL_A, PR_DBL_B 


3.11. Efficiency 

Considerations 




For maximum execution speed, remember the following points when you write 

pixrect programs: 

o pr_get and pr_put () are relatively slow. For fast random access of pix¬ 
els it is usually faster to read an area into a memory pixrect and address the 
. pixels directly. 

□ pr_rop() is fast for large rectangles. 

o pr_vector () is fast. 

□ functions mn faster when clipping is turned off. Do this only if you can 
guarantee that all accesses are within the pixrect bounds. 

□ pr_rop () is three to five times faster than pr_s tencil (). 

D pr_batchrop () cuts down the overhead of painting many small pixrects. 

□ For small standard shapes pr_rop () should be used instead of 
pr polygon 2(). 

o pr_polyline () is an efficient way to draw a series of vectors. 

□ pr_po lypo int () is faster than a series of pr_put s () or single pixel 
pr_rops (). It is useful for implementing new primitives such as curves. 

□ The PR_DBL_DISPLAY_DONTBLOCK attribute of pr_dbl_set (), if 
used appropriately, can speed up animation sequences. 




A 


microsystems 


Revision A of 9 May 1988 







Text Facilities for Pixrects 


Text Facilities for Pixrects. 
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Text Facilities for Pixrects 


The Pixrect library contains higher-level facilities for displaying text. These 
facilities fall into two main categories: a standard format for describing fonts and 
character images, including routines for processing them; and a set of routines 
that take a string of text and a font, and handle various parts of painting that 
string in a pixrect. 



The pixchar stmcture defines the format of a single character in a font. The 
actual image of the character is a pixrect (a separate pixrect for each character) 
addressed by pc_j>r. The entire pixrect gets painted. Characters that do not 
have a displayable image will have NULL in their entry in pc_pr. pc_home is 
the origin of pixrect pc jpr (its upper left comer) relative to the character origin. 
A character’s origin is the leftmost end of its baseline, that is the lowest point on 
characters without descenders. Figure 4-1 illustrates the pc_jpr origin and the 
character origin. 

The leftmost point on a character is normally its origin, but kerning or mandatory 
letter spacing may move the origin right or left of that point pc_adv is the 
amount the destination position is changed by this character, that is, the amounts 
in pc_adv added to the current character origin will give the origin for the next 
character. While normal text only advances horizontally, rotated fonts may have 
a vertical advance. Both are provided for in the font. 



The Pixf ont stmcture contains an array of pixchars, indexed by the charac¬ 
ter code; it also contains the size (in pixels) of its characters when they are all the 
same. If the size of a font’s characters varies in one dimension, that value in 
pf_defaultsize wiU not have an 5 dhing useful in it; however, the other may 
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Still be useful. Thus, for non-rotated variable-pitch fonts, 

pf_def ault size. y will still indicate the unleaded interline spacing for that 

font. 


Figure 4-1 Character and Origins 


pc_pr origin 



4.2. Operations on Pixfonts The commands listed below allow you to load a font to display. A font must be 

loaded before using a text operation. 

Load a Font Pixfont *pf_open(name) ' 

char *name; 


pf_open () returns a pointer to a shared copy of a font in virtual memory. A 
NULL is returned if die font cannot be opened. The path name of the font file 
should be specified, for example: 



name should be in the format described in yfont(5): the file is converted to pix¬ 
font format, allocating memory for its associated structures and reading in the 
data for it from disk. The utility f ontedit(l) is a font editor for designing 
pixel fonts in yfont(5) format. 

The data from a small selection of commonly used fonts is compiled into the pix¬ 
rect library. The names of these built-in fonts are checked against the last com¬ 
ponent of the name. To guarantee that the font is loaded from the disk file 
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Load Private Copy of Font 

Default Fonts 

Close Font 

4.3. Text Functions 
Pixrect Text Display 


Transparent Text 


instead, use pf_open_jpr ivate () instead of pf_open (). 

Pixfont *pf_openj)rivate(name) 
char *name; 

pf_open () returns a pointer to a private copy of a font in virtual memory. A 
NULL is returned if the font cannot be opened. 

Pixfont *pf_d.efault 0 

The procedure pf_def ault performs the same function for the system default 
font, normally a fixed-pitch, 16-point sans serif font with upper-case letters 12 
pixels high. If the environment parameter DEFAULT_FONT is set, its value will 

be taken as the name of the font file to be opened by pf_def ault {). 

( 

pf_close(pf) 

Pixfont *pf; 

When a client is finished with a font, it should call pf_close () to free the 
memory associated with it pf should be a font handle returned by a previous 
call to pf_open () or pf_def ault ( ) . 

The following functions manage various tasks involved in displaying text. 

pf_text(where, op, font, text) 
struct pr_j)rpos where; 
int op; 

Pixfont *font; 
char *text; 

Characters are written into a pixrect with the pf_text () procedure, where is 
the destination for the start of the text (nominal left edge, baseline; see Section 
4.1) op is the raster operation to be used in writing the text, as described in Sec¬ 
tion 3.3, The Op Argument, font is a pointer to the font in which the text is to 
be displayed; and text is the actual null-terminated string to be displayed. The 
color specified in the op specifies the color of the ink. The background of the 
text is painted 0 (background color). 

pf_ttext(where, op, font, text) 
struct pr_prpos where; 
int op ; 

Pixfont *font; 
char *text; 

pf_ttext paints “transparent” text: it doesn’t disturb destination pixels in 
blank areas of the character’s image. The arguments to this procedure are the 
same as for pf_text () . The characters’ bitmaps are used as a stencil, and the 
color specified in op is painted through the stencil. 

For monochrome pixrects, the same effect can be achieved by using PIX_SRC 
I P IX_DST as the function in the op; this procedure is for color pixrects. 
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Auxiliary Pixfont Procedures struct pr_size pf_textbatch (where, lengthp, font, text) 

struct pr_prpos where[]; 
int *lengthp; 

Pixfont *font; 
char *text; 

struct pr__size pf__textwidth (len, font, text) 
int len; 

Pixfont * font; 
char *text; 

pf_textbatch () is used internally by pf_text (); it constructs an array of 
pr_pos structures and records its length, as required by bat chrop (see Sec¬ 
tion 3.6). where should be the address of the array to be filled in, and 
lengthp should point to a maximum length for that array, text addresses the 
null-terminated string to be put in the batch, and font refers to the Pixfont to 
be used to display it. When the function returns, lengthp will refer to a word 
containing the number of pr_pos structures actually used for text. The 
pr_size returned is the sum of the pc_adv fields in their pixchar struc¬ 
tures. 

pf_textwidth ( ) returns a pr_size that is computed by taking the product 
of len, is the number of characters, and pc_adv, the width of each character. 

Text Bounding Box pf_textbound(bound, len, font, text) 

struct pr_subregion *bound; 
int len; 

Pixfont *font; 
char *text; 

pf_textbound may be used to find the boimding box for a string of characters 
in a given font. bound->pos is the top-left comer of the bounding box, 
bound->size . x is the width, and bound->size . y is the height, 
bound->pr is not modified. bound->pos is computed relative to the loca¬ 
tion of the character origin (base point) of the first character in the text. 

Unstructured Text pr_text(pr, x, y, op, font, text) 

Pixrect *pr; 
int X, y, op; 

Pixfont *font; 
char *text; 

pr_ttext(pr, x, y, op, font, text) 

Pixrect *pr; 
int X, y, op; 

Pixfont *font; 
char *text; 

These rmstmctured text functions correspond to the Pixwin functions 
pw_text () and pw_ttext (). prs_text () and prs_ttext () macros 
are also provided, although they are identical to pf_text () and 
pf_ttext () , respectively. 
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4.4. Example 


Here is an example program that writes text on the display surface with pixel 
fonts. 


Figure 4-2 Example Program using Text 


tinclude <pixrect/pixrect_hs.h> 


main () 

{ 


Pixrect *pr; 

Pixfont *pf; 

if (! (pr = pr_open(”/dev/fb”)) I I 

! (pf = pf_open(”/usr/lib/fonts/fixedwidthfonts/screen.r.12"))) 
exit(1); 

pr__text (pr^ 400, 400, PIX_SET, pf, "This is a string."); 

pr_close(pr); ^ 

pf__close (pf) ; ( 

exit(0); 











o 







o 
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Memory Pixrects 


Memory pixrects store their pixels in memory, instead of displaying them on 
some display, are similar to other pixrects but have several special properties. 
Like aU other pixrects, their dimensions are visible in the pr_size and 
pr_depth elements of their Pixrect structure, and the device-dependent 
operations appropriate to manipulating them are available through their 
pr_ops. Beyond this, however, the format of the data which describes the par¬ 
ticular pixrect is also public: pr_data will hold the address of an mpr_data 
stmct described below. Thus, a client may constmct and manipulate memory 
pixrects using non-pixrect operations. There is also a public procedure, 
mem_create (), which dynamically allocates a new memory pixrect, and a 
macro, mpr_st at ic (), which can be used to generate an initialized memory 
pixrect in the code of a cUent program. 


5.1. The mpr_data 

Structure 


The pr_dat a element of a memory pixrect points to an mpr_data stmct, 
which contains the information needed to deal with a memory pixrect. 

linebytes is the number of bytes stored in a row of the primary pixrect This 
is the difference in the addresses between two pixels at the same jc-coordinate, 
one row apart. Because a secondary pixrect may not include the Ml width of its 
primary pixrect, this quantity carmot be computed from the width of the pixrect 
— see Section 3.4. The actual pixels of a memory pixrect are stored someplace 
else in memory, usually an array, which md_image points to; the format of that 
area is described in the next section. The creator of the memory pixrect must 
ensure that md_image contains an even address. md_,of f set is the x,y 


r -^^- 



A 

struct mpr_data { 




int md_linebytes; 
short *md_image; 




struct pr__pos md_offset; 



short md_priinary; 
short md flags; 

}; 

fdefine MP_REVERSEVIDEO 




1 



#define MP_DISPLAY 

2 



fdefine MP_PLANEMASK 

4 



fdefine MP_I386 

8 

/* 

used only on Sun386i^ */ 

#define MP_STATIC 

16 

/* 

ignored on all others. */ 
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! 

I 


Example 


position of the first pixel of this pixrect in the array of pixels addressed by 
md_iinage. md_j)rimary is 1 if the pixrect is primaiy and had its image aUo 
cated dynamically (e.g. by mem_create ()). In this case, md_image will 
point to an area not referenced by any other primary pixrect. This flag is interro 
gated by the pr_destroy () routine: if it is 1 when that routine is called, the 
pixrect’s image memory will be freed. 

The MP_DISPLAY bit will be set in md_f lags if the memory pixrect is actually 
a memory mapped frame buffer. The MP_REVERSEVIDEO bit will be set if 
reversevideo is currently in effect for the pixrect (this is only valid if the pixrect 
depth is 1 bit). The MP_386I bit is non-zero if the pixrect image data is in 80386 
format. 

NOTE This flag is ignored on 680X0 based machines. 

The MP_STATIC is non-zero if the pixrect is static. 

NOTE This flag is ignored on 680X0 based machines. 

md_f lags is present to support memoiy-mapped display devices like the 
Sun—2 monochrome video device, and the bit flipping necessary for Sun386i 
machines. See Chapter 2 for details on 80386 format, and the MP_386I and 
MP_STATIC flags. 

Several useful macros are defined in <pixrect/memvar. h>. These macros 
will greatly increase the productivity of the programmer using memory pixrects, 
as well as the reliability of the code. Two commonly used macros are described 
here; see the others in memvar. h. 

To access a memory pixrect’s bitmap and functions, use the mpr_d () macro. It 
generates a pointer to the private data of a memory pixrect: 

f ----- 

tdefine mpr_d(pr) ((struct mpr_data *) (pr)->pr_data) 

V_1:_ ) 





The mpr_linebytes macro computes the bytes per line of a primary memory 
pixrect given its width in pixels and the bits per pixel. This includes the padding 
to word boimds. It is useful for incrementing pixel addresses in the y direction, 
or calculating line padding in the bitmap. 

' —-^ - >. 

tdefine mpr_linebytes(width, depth) 

( ((pr_product (width, depth)+15) »3) &~1) 
_]__> 


Here is an example program that uses a memory pixrect to do bit manipulations 
on the screen. It opens the frame buffer and copies the bitmap to a memory pix¬ 
rect of the same size. It then goes through each byte of the memory pixrect, left- 
shifting each b)rte. Finally, it copies the modified memory pixrect back into the 
screen pixrect 


Note how (he mpr_linebytes macro is used to find the number of bytes used 
to hold a line of the memory pixrect. The mpr_d () macro is also used to sim¬ 
plify access to the image area of the memory pixrect. 
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Figure 5-1 Example Program using Memory Pixrects 

iinclude <pixrect/pixrect_hs.h> 

#include <stdio.h> 
main () 

{ 

Pixrect *scrn^ *mem; 

int ht^wid; 

char *start, *ptr; 

scrn == pr_open (”/dev/fb”) ; 

wid = scrn->pr_size.x; 

ht = scrn->pr_size.y; 

mem = mem__create (wid^ ht, 1) ; 

pr_rop (mem,. 0,. 0,. wid,ht^PIX__SRC,. scrn^ 0^0); 

start = (char *) mpr_d (mem)->md_image; 

for(ptr = start;ptr < start + mpr_linebytes (wid, 1) * ht;ptr++) *ptr «= 2; 
pr_rop(scrn^ 0^ 0^ wid^ht,PIX_SRC,mem, 0,0) ; 
pr_close (mem) ; 
pr_close(scrn) ; 

} 

V---, 


5.2. Creating Memory The mem_create () and mem_point () functions allow a client program to 

Pixrects create memory pixrects. 

Create Memory Pixrect Pixrect *mem__create (w, h, depth) 

int w, h, depth; 

A new primary pixrect is created by a call to the procedure mem_create (). w, 
h and depth specify the width and height in pixels, and depth in bits per pixel 
of the new pixrect. Sufficient memory to hold those pixels is allocated and 
cleared to 0, new mpr_data and Pixrect structures are allocated and initial¬ 
ized, and a pointer to the pixrect is returned. If this can not be done, the return 
value is NULL. On Sun386i systems, the memory pixrects created by 
mem_create () set the MP_I38 6 flag to 1 (true). 

On 32 bit systems (such as the Sun-3 and Sun-4) the created pixrect wiU have 
each scan line padded out to a 32 bit boundary, unless it is only 16 bits wide; that 
is, the md_linebytes structure member wiU contain either 2 or a multiple of 
4. In older Sun releases pixrects created by mem_c re ate () were always pad¬ 
ded to a 16 bit boundary. 


Create Memory Pixrect from 
an Image 


Pixrect *mem_j)oint(width, height, depth, data) 
int width, height, depth; 
short *data; 

The mem_j)oint () routine builds a pixrect structure that points to a dynami¬ 
cally created image in memory. Qient programs may use this routine as an alter¬ 
native to mem_create () if the image data is dready in memory, width and 
height are the width and height of the new pixrect, in pixels, depth is the 
depth of the new pixrect, in number of bits per pixel, data points to the image 
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o 

to be associated with the pixrect Unlike the mem_create () routine, the 
mem_point () routine does not set the MP_38 61 flag; the pixrect remains in 
680X0 format 

Note that mem_jpoint () expects each line of the memory image to be padded 
to a 16 bit boundary. Also, mem_j)oint () does not set the md_primary flag 
so the image will not be automatically freed when the pixrect is destroyed. 

Example Here is an example program which uses a memoiy pixrect to invert the frame 

buffer contents from top to bottom. It opens the default frame buffer and creates 
a memory pixrect of the same size. It then copies rows of pixels from the frame 
buffer to the memory pixrect in reverse order. Finally, it copies the memory pix¬ 
rect back to the frame buffer. 


Figure 5-2 Example Program using Memory Pixrects 

c -- 

#include <pixrect/pixrect__hs . h> 

main () 

{ 

Pixrect *pr^ *tmp; 
int yin,, yout; 

if (! (pr = pr_open("/dev/fb”) ) II 

! (tmp = 

mem_create (pr->presize. X, pr->pr_size . y,. pr~>pr_depth) ) ) 
exit(1); 

for (yin = 0, yout = pr->pr_size.y - 1; yout >= 0; yin++, yout—) 
pr_rop(tmp^ 0, yout, pr->pr_size.x, 1, PIX_SRC, pr, 0, yin); 

pr_rop(pr, 0, 0, pr->pr_size .x, pr->pr_size .y, PIX__SRC, tmp, 0, 0) ; 

exit(0); 

} 

-—..> 


o 


5.3. Static Memory #define nipr_static (name, w, h, depth, image) 

Pixrects int w, h, depth; 

short *image; 

A memory pixrect may be created at compile time by using the 
mpr_static 0 macro, name is a token to identify the generated data objects; 
w, h, and depth are the width and height in pixels, and depth in bits of the pix¬ 
rect; and image is the address of an even-bsde aligned data object that contains 
the pixel values in the format described below, with each line padded to a 16 bit 
boundary. 

If static structures are desired, the macro mpr_static_static should be 
used instead. 

kJ 



Revision A of 9 May 1988 





Chapter 5 — Memory Pixrects 55 


The macro generates two structures: 


. . ' ' - 

s 

struct mpr__data name_data; 


Pixrect name; 


V 

. -. J 


The mpr_data is initialized to point to all of the image data passed in; the 
Pixrect then refers to mem_ops and to name_data. On a Sun386i 
machine, the mp_STATIC flag will be set in the md_flags byte of the pixrect 
data structure; see Chapter 2 for details. Note: Contrary to its name, this macro 
generates structures of storage class exterirT 

In memory, the upper-left comer pixel is stored at the lowest address. This 
address must be even. That first pixel is followed by the remaining pixels in the 
top row, left-to-right. Pixels are stored in successive bits without padding or 
alignment 

Each row of pixels is rounded to at least a 16 bit boundary. For best performance 
on 32 bit systems, pixel rows should be rounded to 32 bit boundaries 
(mem_creat& does this automatically). However, 16 bit rounding is required for 
static pixrects and mem_point. 

Memory pixrects with depths of 1, 8,16,24, and 32 bits are currently supported 
by the pixrect library. If source and destination are both memory pixrects they 
must have an equal number of bits per pixel. 

NOTE If you are running a Sun386i machine. A pixrect’s image data will be converted 

to 80386format before being displayed. See Chapter 2 for details. 

Memory pixrects can be used to get data from and send data to the display dev¬ 
ice. Several routines exist for interfacing Pixwins with memory pixrects. These 
include pw read (), pw_rop () and pw^wr it e (). Refer to the SunView 1 
Programmer’s Guide for more details. For applications using the raw device 
without SunView, pr_rop () can be used! for operations on memory pixrects. 

Another use of memory pixrects is for processing images that not intended for 
display. User programs can write directly into a pixrect using parameters found 
in the mpr_dat a structure, or they can use mein_j3oint () for a previously 
created image. Memory pixrects can also be written to raster files using the facil¬ 
ities described in Chapter 6. 


5.5. Using Memory 
Pixrects 


5.4. Pixel Layout in 
Memory Pixrects 
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File I/O Facilities for Pixrects 

6.1. Writing and Reading Raster Files 

Run Length Encoding.. 

Write Raster File. 

Read Raster File. 

6.2. Details of the Raster File Format . 

6.3. Writing Parts of a Raster File. 

Write Header to Raster File. 

Initialize Raster File Header. 

Write Image Data to Raster File . 

6.4. Reading Parts of a Raster File.. 

Read Header from Raster File. 

Read Colormap from Raster File 

Read Image from Raster File. 

Read Standard Raster File. 



























6.1. Writing and Reading 
Raster Files 

Run Length Encoding 



File I/O Facilities for Pixrects 


Sun Microsystems, Inc. has specified a file format for files containing raster 
images. The format is defined in the header file <rasterf ile. h>. The pix- 
rect library confains routines to peifonn I/O operations between pixrects and files 
in this raster file format. This I/O is done using the routines of the C Library 
Standard I/O package, requiring the caUer to include the header file 
<stdio .h>. 

The raster file format allows multiple types of raster images. Unencoded, and 
run-length encoded formats are supported directly by the pixrect library. Support 
for customer defined formats is implemented by passing raster files with non¬ 
standard types through filter programs. Sun supplied filters are found in the 
directory /usr/lib/rasf liters. This directory also includes sample 
source code for a filter that corresponds to one of the standard raster file types to 
facilitate writing new filters. 

The sections that follow describe how to store and retrieve an image in a 
rasterfile. 

The run-length encoding used in raster files is of the form 

<byte><byte>...<ESC><0>...<byte><ESC><count><byte>... 

where the counts are in the range 0..255 and the actual number of instances of 
<byte> is <count>+l (i.e. actual is L.256). One-or two-character 
sequences are left unencoded; three-or-more character sequences are encoded as 
<ESC><count><byte>. <ESC> is the character code 128. Each single <ESC> 
in the input data stream is encoded as <ESC><0>, because the <count> in this 
scheme can hever be 0 (the actual count can never be 1). <ESC><ESC>is 
encoded as <ESC><1><ESC>. 

This algorithm will fail (make the compressed data bigger than the original data) 
only if the input stream contains an excessive number of one- and two-character 
sequences of the <ESC> character. 
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Write Raster File 


int pr_dump(input_pr, output, colormap, type, copy_flag) 
Pixrect *input_pr; 

FILE * output; 
colormap_t *colormap; 
int type, copy_flag; 

The pr_d\amp () procedure stores the image described by a pixrect onto a file. 

It normally returns 0, but if any error occurs it returns PIX_ERR. The caUer can 
write a rectangular sub-region of a pixrect by first creating an appropriate 
input_pr via a call to pr_region (). The output file is specified via out¬ 
put. The specified output type should either be one of the following standard 

t)^es or correspond to a customer provided filter. 

-- 

#define RT_OLD 0 

♦define RT_STANDARD 1 
♦define RT_BYTE_ENCODED 2 

___ / 


The RT_STANDARD type is the common raster file format in the same sense that 
memory pixrects are the common pixrect format: every raster file filter is 
required to read and write this format. The RT_OLD type is very close to the 
RT_STANDARD type; it was the former standard generated by old versions of 
Sun software. The RT_BYTE_ENCODED type implements a run-length encoding 
of bytes of the pixrect image. This usually results in shorter files, although 
pathological images may expand by 50%. 

Specifying any other output type causes pr_dump () to pipe a raster file of 
RT_STANDARD type to the filter named convert. type, looking first in direc¬ 
tories in the user’s $P ATH environment variable, and then in the directory 
/usr/lib/rasf liters, type is the ASCII corresponding to the specified 
type in decimal. The output of the filter is then copied to output. 



It is strongly recommended that customer-defined fonnats use a type value of 100 
or more, to avoid conflicts with additions to the set of standard types. The 
RT_EXPERIMENTAL type is reserved for use in the development of experimental 
filters, although it is no longer treated specially. 

-—- ^ 

♦define RT_EXPERIMENTAL 65535 

___ / 


pr_dump () and other functions that start filters wait until the filter process 
exits before returning, so caution is advisable when working with experimental 
filters. 


For pixrects displayed on devices with colormaps, the values of the pixels are not 
sufficient to recreate the displayed image. Thus, the image’s colormap can also 
be specified in the call to pr_dump (). If the colormap is specified as NULL 
but input j)r is a non-monochrome display pixrect, pr_dump {) will attempt 
to write the colormap obtained from input_pr (via pr getcolormap). The 
following structure is used to specify the colormap associated with input_pr: 
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typedef struct { 
int type; 
int length; 

unsigned char *map[33; 

} colormap^t; 

.- . . 

\ 

The colormap type should be one of the Sun supported types; 


#define RMT_NONE 0 
#define RMT_EQUAL_RGB 1 
#define RMT_RAW 2 

> 

. 

J 


If the colormap type is RMT_NONE, then the colormap length must be 0. This 
case usually arises when dealing with monochrome displays and 1-bit deep 
memory pixrects. If the colormap type is RMT_EQUAL_RGB, then the map array 
should specify the red (map [ 0 ]), green (map [ 1 ]) and blue (map [ 2 ]) color- 
map values, with each vector in the map array being of the same specified color- 
map length. If the colormap type is RMT_RAW, the first map array (map [ 0 ]), 
should hold length bytes of colormap data, which will not be inteipreted by 
the pixrect library. 

Finally, copy_f lag specifies whether or not input_pr should be copied to a 
temporaiy pixrect before the image is output. The copY_f lag value should be 
non-zero if input_pr is a pixrect in a frame buffer that is likely to be asyn¬ 
chronously modified. The copy flag is also automatically set non-zero for secon¬ 
dary pixrects, to simplify the code. Note that use of copy_f lag still will not 
guarantee that the correct image will be output unless the pr_rop {) to copy 
from the frame buffer is made uninterruptible. 
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Read Raster File 


Figure 6-1 




Example Program using pr__dump () 


#include 

♦include 

♦include 

♦include 


<stdio.h> 

<sys/types.h> 
<pixrect/pixrect.h> 
<pixrect/pr_io.h> 


main() 

{ 

Pixrect *screen^ *icon; 

FILE ^output = stdout; 
colormap_t *colormap = 0; 
int type = RT_STANDARD; 
int copy_flag = 1; 

if (! (screen = pr_open("/dev/fb”)) I I 

! (icon = pr_region (screen1050, 10, 64, 64) )) 
exit(1); 

pr_dump(icon, output, colormap, type, copy_flag); 
pr_close(screen); 

exit(0); 

} 


Pixrect *preload(input, colormap) 

FILE *input; 
colormap_t *colormap; 

The pr_load () function can be used to retrieve the image stored in a raster file 
into a pixrect. The raster file’s header is read from input, a pixrect of the 
appropriate size is d 5 mamicaUy allocated, the colormap is read and placed in the 
location addressed by colormap, and finally the image is read into the pixrect 
and the pixrect returned. If any problems occurs, pr_load () returns NULL. 

As with pr_dump (), if the specified raster file is not of standard type, 
pr_load () first mns the file through the appropriate filter to convert it to 
RT_STANDARD type and then loads the output of the filter. 

Additionally, if colormap is NULL, pr_load () wiU simply discard any and 
all colormap information contained in the specified input raster file. If color- 
map is non-null pr_load () will load the colormap data even if the type and 
length specified do not match that of the file (see pr__load_colormap () 
below). 


o 
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Figure 6-2 Example Program using preload () 

---- __ 

tinclude <stdio.h> 

♦include <sys/types.h> 

♦include <pixrect/pixrect.h> 

♦include <pixrect/pr_io.h> 

main() 

1 

Pixrect *screen,^ *icon; 

FILE *input = stdin; 
colormap__t colormap; 

colormap.type = RMT_NONE; 

if (!{screen = pr_open(”/dev/fb")) I I 

!(icon = preload(inputs Scolormap))) 
exit(1); 

if (colormap.type === RMT_EQUAL_RGB) 

pr__putcolormap (screen, 0, colormap. length, 
colormap.map[0], colormap.map[1], 
colormap .map [2 ]) ; 

pr__rop (screen, 1050, 110, 64, 64, PIX_SRC, icon, 0, 0) ; 
pr_close(screen); 

exit(0); 

} 

V___> 


6.2. Details of the Raster A handful of additional routines are available in the pixrect library for manipulat- 

File Format ing pieces of raster files. In order to understand what they do, it is necessary to 

understand the exact layout of the raster file format. 

The raster file is in three parts: first, a small header containing eight 32-bit 
int’s; second, a (possibly empty) set of colormap values; third, the pixel image, 
stored a line at a time, in increasing y order. 

The image is essentially laid out in the file the exact way that it would appear in a 
static memory pixrect. In particular, each line of the image is rounded out to a 
multiple of 16 bits, corresponding to the rounding convention used by static pix¬ 
rects. 

The header is defined by the following structure: 
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The ras_magic field always contains the following constant: 



The ras_width, ras_height and ras_depth fields contain the image’s 
width and height in pixels, and its depth in bits per pixel, respectively. The depth 
is usually either 1 or 8, corresponding to the standard frame buffer depths. 

The ras_length field contains the length in bytes of the image data. For an 
unencoded image, this number is computable from the ras_width, 
ras_height, and ras_depth fields, but for an encoded image it must be 
explicitly stored in order to be available without decoding the image itself. Note 
that the length of the header and of the possibly empty colormap values are not 
included in the value in the ras_length field; it is only the image data length. 
For historical reasons, files of type RT_OLD wiU usually have a 0 in the 
ras_length field, and software expecting to encounter such files should be 
prepared to compute the actual image data length if it is needed. The 
ras_maptYpe and ras_maplength fields contain the type and length in 
bytes of the colormap values, respectively. 

If the ras_maptype is not RMT_NONE and the ras_maplength is not 0, 
then the colormap values are the ras_maplength bytes immediately after the 
header. These values are either uninterpreted b 5 d;es (usually with the 
ras_mapt ype set to RMT_RAW) or the equal length red, green and blue vec¬ 
tors, in that order (when the ras maptype is RMT_EQUAL_RGB). In the latter 
case, the ras_maplength must be three times the size in bytes of any one of 
the vectors. 

6.3. Writing Parts of a The following routines are available for writing the various parts of a raster file. 

Raster File Many of these routines arc used to implement pr_dump (). First, the raster file 

header and the colormap can be written by calling pr_dump_header {). 

Write Header to Raster File int pr_dump_header (output, rh, colormap) 

FILE *output; 
struct rasterfile *rh; 
colOrmap_t *colormap; 

pr_dump_header () returns PIX_ERR if there is a problem writing the header 
or the colormap, otherwise it returns 0. If the colormap is NULL, no colormap 
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values are written. 

Initialize Raster File Header Pixrect *pr_diamp_init (input_pr, rh, colormap, 

type, copy_flag) 

Pixrect *input__pr; 
struct rasterfile *rh; 
colormap_t *colormap; 
int type, copy_flag; 

For clients that do not want to explicitly initialize the rasterfile struct this routine 
can be used to set up the arguments for pr_dump_header (). The arguments 
to pr_dump_init () correspond to the arguments to pr_dTamp (). However, 
pr_dump_init {) returns the pixrect to write, rather than actually writing it, 
and initializes the stmcture pointed to by rh rather than writing it. If colormap is 
NULL, the ras_maptype and ras_maplength fields of rh will be set to 
RMT_NONE and 0, respectively. 

If any error is detected by pr_dump_init (), the returned pixrect is NULL. If 
there is no error, the copy_f lag is zero, and the input pixrect is suitable for 
direct dumping (a primary memory pixrect), the returned pixrect is simply 
input_pr. However, if copy_f lag is non-zero, or the input pixrect carmot 
be dumped directly, the returned pixrect is dynamically allocated and the caller is 
responsible for deallocating it with pr_de st ro y () when it is no longer 
needed. 

int pr_dump__image (pr, output/ rh) 

Pixrect *pr; 

FILE *output; 
struct rasterfile *rh; 

The actual image data can be output via a call to pr_dump_image (). This 
routine returns 0 unless tiiere is an error, in which case it is PIX_ERR. It cannot 
write the image in a non-standard (filtered) format, since by the time it is called 
the raster file header has already been written. 

Since these routines sequentially advance the output file’s write pointer, 
pr_dump_image {) must be called after pr_dump_header () . 

The following routines are available for reading the various parts of a raster file. 
Many of these routines are used to implement pr_load (). Since these rou¬ 
tines sequentially advance the input file’s read pointer, rather than doing random 
seeks in the input file, they should be called in the order presented below. 

Read Header from Raster File int pr_load_header (input, rh) 

FILE *input; 

struct rasterfile *rh; 

The raster file header can be read by calling pr_load_header (). This rou¬ 
tine reads the header from the specified input, checks it for validity and initializes 
the specified rasterfile structure from the header. The return value is 0 
unless there is an error, in which case it is PIX_ERR. 


6.4. Reading Parts of a 
Raster File 


Write Image Data to Raster 
File 
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Read Colormap from Raster int pr_load._colormap (input, rh, colormap) 

File FILE *input; 

struct rasterfile *rh; 
colormap_t *colonnap; 

If the header indicates that there is a non-empty set of colormap values, they can 
be read by calling pr_load_colormap (). If the specified colormap is 
NULL, this routine will skip over the colormap values by reading and discarding 
them. If the type and length values in colormap do not match the input file, 
pr_load_colormap () will allocate space for the colormap with itialloc, 
read the colormap, and modify colormap before returning. If this occurs, the 
space allocated can be released with a free (colormap->map [ 0 ]). 

The return value is 0 unless there is an error, in which case it is PIX_ERR. 


Read Image from Raster File 


Pixrect *pr_load_iinage (input, rh, colormap) 
FILE *input; 
struct rasterfile *rh; 
colormap_t *colormap; 


An image can be read by calling pr_load_image (). If the input is a standard 
raster file type, this routine reads in the image directly. Otherwise, it writes the 
header, colormap, and image into the appropriate filter and then reads the output 
of the filter, hi this case, both the rasterfile and the colormap structures will be 
modified as a side-effect of calling this routine. In either case, a pixrect is 
dynamically allocated to contain the image, the image is read into the pixrect, 
and the pixrect is returned as the result of calling the routine. If there is an error, 
the return value is NULL. 



Read Standard Raster File Pixrect *pr_load_std_image(input, rh, colormap) 

FILE *input; 

struct rasterfile *rh; 

colormap_t colormap; 

If it is known that the image is from a standard raster file type, then it can be read 
in by calling pr_load_std_image (). This routine is identical to 
pr_load_image (), except that it will not invoke a filter on non-standard ras¬ 
ter file types. 
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Writing a Pixrect Driver 


Sun has defined a common programming interface to pixel addressable devices 
that enables, in particular, device independent access to aU Sun frame buffers. 
This interface is called the pixrect interface. Existing Sun supported software 
systems access a frame buffer through the pixrect interface. Sun encourages cus¬ 
tomers with other types of frame buffers (or other types of pixel addressable dev¬ 
ices) to provide a pixrect interface to these devices. 

This chapter describes how to write a pixrect driver. It is assumed that you have 
already read Chapter 3, Pixrect Operations', it describes the progr a m m i ng inter¬ 
face to the basic operations that must be provided in order to generate a complete 
pixrect implementation. It is also assumed that you have a copy of Writing Dev¬ 
ice Drivers The section in that manual on writing the kernel device driver portion 
of the pixrect implementation is important. 

This chapter contains auxiliary inaterial of interest only to pixrect driver imple¬ 
mentors, not programmers accessing the pixrect interface. This document 
explains how to install a new pixrect driver into the software architecture so that 
it may be used in a device independent marmer. Also, utilities and conventions 
that may be of use to the pixrect driver implementor are discussed. 

This chapter walks through the source code for the CG-1 pixrect driver. The 
CG-1 is the Sim-1 color frame brkffer. Using this particular driver as an example 
has no significance; another pixrect driver would have worked just as weU. 

The actual source code that is presented here is boiler-plate, i.e., almost every 
pixrect driver implementation wiU be similar. You should be able to make your 
own driverjust from the documentation alone. However, a complete source 
example for an existing pixrect driver would probably expedite the development 
of your own driver. The complete device specific source files for the Sim-1 color 
frame buffer pixrect driver is available as a source code purchase option (avail¬ 
able without a UNIX source license). 

A.I. What You’ll Need These are the tools and pieces that you’ll need before assembling your pixrect 

driver: 

□ You need the correct documentation: 

SunView 1 Programmer’s Guide 
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A.2. Implementation 
Strategy 


A.3. Fil^ Generated 



SunView 1 System Programmer’s Guide 
Writing Device Drivers 

□ You need to know how to drive the hardware of your pixel addressable dev¬ 
ice. At a minimum, a pixel addressable device must have the ability to read 
and write single pixel values. (One could imagine a device that doesn’t even 
meet the minimum requirements being used as a pixel addressable device. 
We will not discuss any of the ways that such a device might fake the 
minimum requirements). 

p You must have a UNIX kernel building environment. No extra source is 
required. 

□ Yoii must have the current pixrect library file and its accompanying header 
files. No extra source is required. 

This is one possible step-by-step approach to implementing a pixrect driven 

□ Write and debug pixrect creation and destruction. This involves the pixrect 
kernel device driver that lets you open(2) and rranap(2) the physical device 
from a user process. The private cgl_make routine must be written. The 
cgl_region and cgl_destroY pixrect operation must be written. 

□ Write and debug the basic pixel rectangular region function. The 
cgl_putattributes and cgl_putcolormap pixrect operations must 
be written in addition to the cgl_rop routine. 

o Write and debug batchrop routines. The cgl_batchrop pixrect operation 
must be written. 

p Write and debug vector drawer. The cgl_vector pixrect operation must 
be written. 

p Write and debug remaining pixrect operations: cgl_stencil, cgl_get, 
cgl_put, cgl_getattributes and cgl_getcolormap. 

p If the device is to run with SunView, build a kernel with minimal basic pixel 
rectangle function for use by the cursor tracking mechanism in the SunView 
kernel device driver. Also include the colormap access routines for use by 
the colormap segmentation mechanism in the SunView kernel device driver. 

p Load and test SunView programs with new pixrect driver. Experience has 
shown that when you are able to run released SunView programs that your 
pixrect driver is in pretty good shape. 

Here is the list of source files generated that implement the example pixrect 

driver: 

□ cglreg. h - A header file describing the structure of the raster device. It 
contains macros used to address the raw device. 

p cgl var. h - A header file describing the private data of the pixrect. It con¬ 
tains external references to pixrect operation of this driver. 
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□ / sys / sundev/ cgone. c - The pixrect kernel device driver code, 
o cgl. c - The pixrect creation and destruction routines. 

□ cgl_region. c - The region creation routine. 

□ pr_makef un. c - Replaces an existing module and contains the vector of 
pixrect make operations. 

□ cgl_bat ch. c - The batchrop routine. 

□ cgl_colormap. c - The colormap access and attribute setting routines. 

□ cgl_getput. c - The single pixel access routines. 

□ cgl_rop. c - The basic pixel rectangle manipulation routine. 

□ cgl_stencil. c - The stencil routine. 

□ cgl_vec. c - The vector drawer. 

□ cgl_curve. c The curved shape routine. 

□ cgl_polyline. c The polyline routine. 

Memory Mapped Devices Some devices are memory mapped; a good example is the bw2, the Sun-2 mono¬ 

chrome video frame buffer. With such devices, their pixels are manipulated 
directly as main memory; there are no device specific registers through which the 
pixels are accessed. Memory mapped devices are able to rely on the memoiy 
pixrect driver for many of its operations. The only files that the Sun 2 mono¬ 
chrome video frame buffer supplies are: 

□ bw2 var. h - A header file describing the private data of the pixrect. It con¬ 
tains external references to pixrect operation of this driver. 

□ / sys / sundev/bwtwo. c - The pixrect kernel device driver code. 

□ bw2 . c - The pixrect creation and destmetion routines. 

The operations vector for the Sun 2 monochrome pixrect driver is: 
r —— .N 

struct pixrectops bw2_ops = { 

mem_rop, mem_stencil, mem_batchrop, 

0, bw2_d.estroy, m§m_get, niem_j>ut, mem_vector, 
mem_region, mem_putcolormap, mem_getcolormap, 
mem_putattributes , mem_getattributes 

}; 

V_____ , 


A.4. Pixrect Private Data Each pixrect device must have a private data object that contains instance 

specific data about the state of the driver. It is not acceptable to have global data 
shared among all the pixrects objects. The device specific portion of fte pixrect 
data must contain certain information: 

□ An offset from the upper left-hand comer of the pixel device. This offset, 
plus the width and height of the pixrect from the public portion, is used to 
determine the clipping rectangle used during pixrect operations. 
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o A flag for distinguishing between primary and secondary pixrects. Primary 

pixrects are the owners of dynamically allocated resources shared between 
primary and secondary pixrects. 

□ A file descriptor to the pixrect kernel device. Usually, the file descriptor is 
used while mapping pages into the user process address space so that the 
device may be addressed. One could imagine a pixrect driver that had some 
of its pixrect operations implemented inside the kernel. The file descriptor 
would then be the key to communicating with that portion of the package via 
read(2), write(2) and ioctl(2) system calls. 

Here is other possible data rhaintained in the pixrect’s private data: 

□ For many devices, a virtual address pointer is part of the private data so that 
the device can be accessed from user code. 

□ For color devices, there is a mask to enable access to specific bit planes. 

□ For monochrome devices, there is a video invert flag. This replaces the 
colormap of color devices. 

A.5. Creation and This section covers the code for pixrect object creation and destruction. Code for 

Destruction the Sun-1 color frame buffer pixrect driver is presented as an example. 

There are two public pathways to creating a pixrect: 

a pr_open () creates a primary pixrect. 

o pr_region () creates a secondary pixrect which specifies a subregion in 
an existing pixrect. 

There are two public pathways to destroying a pixrect: 

o pr_destroy{) destroys a primary or secondary pixrect. Clients of the 
pixrect interface are responsible for destroying all extant secondary pixrects 
before destroying the primary pixrect from which they were derived. 

n pr_close() simply calls pr_destroy (). 

Creating a Primary Pixrect In this section, the private cgl_make pixrect operation is described. This is the 

flow of control for pr_open {>: 

□ Higher levels of software call pr_open (), which takes a device file name 
(e.g., /dev/cgoneO). 

□ pr_open () c^ns the device and finds out its type and size via an FBKXj- 
TYPE ioctl(2) call (see <sun/fbio. h>). 

n pr_open () uses the type of pixel addressable device to index into the 
pr_inakef un array of procedures (more on this later) and calls the refer¬ 
enced pixrect make function, cgl_make. 

□ cgl_make returns the primary pixrect (it workings are discussed below). 

o pr_open() closes its handle on the device aiKl the pixrect is returned. 
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Here is a partial listing of cgl. c that contains code that is important to the 
cgl_make procedure. As it is for other code presented in this document, it is 
here so you can refer back to it as you read the subsequent explanation. Some 
lines are numbered for reference and normal C comments have been removed in 
favor of the accompanying text. 
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Line cgl.7 does some consistency checking to make sure that the dimensions of 
the pixel addressable device and the client’s idea about the dimensions of the 
device match. 


.. 

struct *pixrect pr_makefromfd (fd,^ 

size, depth, devdata. 


curdd, 

struct 

ininapbytes, privdatabytes, mmapoffsetbytes) 
pr_size size; 


struct 

p r_devdat a * * devdata, 

**curdd; 


int 

fd, depth, mmapbytes. 

privdatabytes, 


V 

mmapoffsetbytes; 


J 


Line cgl.8 caUs the pixrect library routine pr_makef romf d to do most of the 
work: 


n Allocates a pixrect structure object using the calloc library call. The 
pixrect is filled in with size and depth parameters. 

□ Allocates an object of the size privdatabytes using the calloc library call 
and placing a pointer to it in the pr data field of Ae allocated pixrecL 

□ dup(2)s the passed in file descriptor/ri so that when the caller closes the file 
descriptor the device wouldn’t close. 

o inmap(2) allocates and maps to the device mmapbytes of space. 

o If an error is detected during any of the above calls, an error is written to the 
standard error output. A NULL pixrect handle is returned in this case. 

o Returns the allocated pixrect. 

This brings us to the issue of minimizi n g resources used by the pixrect driver. 
andpr_open, cgl_make, can be (and are) called many times thus creating a 
situation in which there are many primary pixrects open at a time. A pixrect 
should maintain an open file descriptor and (usually) a non-trivial amount of vir¬ 
tual address space mapped into the user process’s address space. Both the 
number of open file descriptors and the virtual address space (maximum 16 
megabytes) are finite resources. However, multiple open pixrects can share aU 
these resources. 

The pixrect library supports a resource sharing mechanism, part of which is 
implemented in pr_makef romf d. The devdata parameter passed to 
pr_makef romf d is the head of a linked list of pr_devdata structures of 
which there is one per pixrect driver. It is sufficient to say that through the data 
maintained on this list, sharing of the scarce resources described above can be 
accomplished. 

The curdd parameter passed to pr_makef romf d is set to be the 
pr_devdata stmcture that applies to the device identified by f d. 

Lines cgl.9 through eg 1.14 are concerned with initializing the pixrect’s private 
data with dynamic information described in dd (curdd in the previous para¬ 
graph) and static information about the pixel addressable device. 
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Line cgL15 is where the video signal for the device is enabled. By convention, 
every raster device should make sure that it is enabled. 

Creating a Secondary^ixrect In this section, the cgl_r egion pixrect operation is described. Here is all of 

cgl_region.c. 

-^^ 

struct pixrect *cgl_£region (src) 

struct pr^subregion src; 

{ 

register struct pixrect *pr; 

register struct cglpr *scgpr = cgl_d (src.pr)^ *cgpr; 
int zero =0; 

pr_clip (&src,^ &zero) ; /* cgl_region. 1*/ 

if < (pr =f (struct pixrect *)calloc(l, sizeof (struct pixrect))) == 0) 
return (0); /* cgl_region.2*/ 

if ((cgpr = (struct cglpr *)calloc(l, sizeof (struct cglpr))) == 0) { 

free(pr); /* cgl_region.3*/ 
return (0); 

pr->pr_ops = &cgl_ops; /* cgl_region.4*/ 

pr->pr_size = src.size; /* cgl_region.5*/ 

pr->pr_depth = CG1_DEPTH; /* cgl_region.6*/ 

pr->pr_data = (caddr_t)cgpr; /* cgl_region.7*/ 

cgpr->cgpr_fd = -1; /*^ cgl_region. 8*/ 

cgpr->cgpr__va = scgpr~>cgpr__va; //* cgl_region. 9*/ 

cgpr->cgpr_j> lanes = scgpr->cgpr_planes; /*cgl_region.10*/ 

cgpr->cgpr_offset.X = scgpr->cgpr__offset.x + src.pos.x; /*cgl_region.11*/ 
cgpr“>cgpr_of f set. y = scgpr-->cgpr__of f set .y + src.pos.y; /*cgl_region. 12*/ 
return (pr); 

} 

V__^_> 


cgl_region is less complex then cgl_make. The first thing done is to clip 
the requested subregion to fall within the source pixrect (line cgl region,!). 

pr_clip(dstp, srcp) 

struct pr_subregion *dstp; 
struct pr_jDrpos *srcp; 

pr_clip adjusts the position and size of dstp, the destination pixrect subre¬ 
gion, to fan within dstp->pr. If * scrp, the source pixrect position, is not 
zero then the position of the source is clipped to fall within dstp. 

Next, objects are allocated for the pixrect and the pixel addressable device’s 
private data (line cgl_region,2 and cgI_region,3). Then, similarly to the later 
part of cgl_make, the two new data objects are initialized (lines cgI_region,4 
through cgl_regionJ2). One thing to note is that the cgl driver uses a -I in the 
file descriptor field of the pixrect’s private data to indicate that this pixrect is 
secondary (line cgl jregion,8). 

r 
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Destroying a Pixrect In this section, the cgl_destr oy pixrect operation is described. It works on 

secondary and primary pixrects. Here is more of cgl. c. 


/- 


A 

cgl_destroy(pr) 

struct pixrect *pr; 

register struct cglpr *cgpr; 

1 


if (pr == 0) 

return (0); 

if (cgpr = cgl_d(pr)) { /*cgl.30*/ 

if (cgpr->cgpr__fd != -1) { /*cgl.31*/ 

pr__unmakefromfd (cgpr->cgpr fd^ &cgldevdata) ; 

} 

free(cgpr); /*cgl.33*/ 

} 

free(pr); /*cgl.34*/ 

return (0); 

} 

^__ 

/*cgl.32*/ 



-J 


Note that dynamic memory is freed (lines cgl 33 and cgl 34), Also, note that 
only a primary pixrect (as indicated by a file descriptor that is not -1) invokes a 
caU to pr_unitiakef romf d (line cgl 32), 

pr^unmakefromfd(fd, devdata) 

struct pr__devdata **devdata; 
int f d; 


The pr_makef un () 

Operations Vector 


This pixrect library routine is the counterpart of pr_makef romf d (). If the 
device identified by the file descriptor f d has no more pixrects associated with it 
(as determined from devdata) then the resources associated with it are 
released. 


As mentioned above, pr_open () calls cgl_make () through the 
pr_makef un () procedure vector. This is what pr_makef un () looks like (it 
is the sole contents of pr_makef un. c): 


#include <pixrect/pixrect_hs.h> 
tinclude <sun/fbio.h> 

Pixrect *(*pr_makefun[FBTYPE_LASTPLUSONE])() = { 
bwl_make, 
cgl_make, 
bw2_make, 
cg2_make, 
gpl_make, 

0 /* bw3_inake */ , 

0 /* cg3_make */ , 

0 /* bw4_inake */ f 

cg4_make 

}; 
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pr itiakef un () is the routine that pulls in all the code from the different frame 
buffers. If a site is not going to use programs on more than one kind of display, 
the unused slots can be commented out to prevent the code for the unused display 
from being loaded. This has the advantage of reducing disk space usage. How¬ 
ever, working set size will presumably not be affected due to virtual memory not 
touching unused code. 

For both the case of adding and deleting drivers, loading a compiled version of 
this edited file will have the effect of ignoring die commented out device drivers. 

When adding some new pixrect driver, you need to assign it some unused con¬ 
stant from <sun/fbio. h>, e.g., FBTYPE_NOTSUNl. This then becomes the 
device identifier for your new pixrect driver. You need to generate a new version 
of the source file pr_makef un. c with the above data structure except that file 
array entry pr_makef un [FBTYPE_NOTSUNl] would contain the pixrect make 
procedure for your FBTYPE_NOTSl]Nl pixrect driver (line pr_makef un. 1). 

^ The old pr_make f un. o in the pixrect library could be replaced with your new 

^ pr_makef un. o using ar(l). 

A.6. Pixrect Kernel Device A pixrect kernel device driver supports the pixel addressable device as a com- 
Driver plete UNIX device. It also supports use of this device by fixe SunView driver so 

that the cursor cah be tracked and the colormap loaded within the kernel. The 
document Writing Device Drivers for the Sun Workstation contains the details of 
device driver construction. It also contains an overview. 

The code in this section comes from cgone. c. In the kernel, suffixes that end 
with a number (like cgl) confuse the conventions surrounding device driver 
names. A number suffix refers to the minor device number of a device. There¬ 
fore, in our example, cgl becomes cgone where the naming has something to 
do with the pixrect kernel device driver. 

Configurable Device Support Raster devices typically hang off a high speed bus (e.g.. Multibus) or are plugged 

into a high speed communications port. At kernel building time the UNIX auto¬ 
configuration mechanism is told what devices to expect and where they should be 
found. At boot time thesauto^configuration mechanism checks to see if each of 
the devices it expects are present. 

This section deals with the auto-configuration aspects of the driver. This driver 
is written in the conventionaUstyle that supports multiple units of the same dev¬ 
ice type. It is recommended that you follow this style even if you aren’t antici¬ 
pating multiple pixel addressable devices of your type on a single UNIX system. 


/- 



#include 

"cgone.h” 


#include 

”win.h" 


i #if NCGONE > 0 


#include 

”.,/h/param.h" 


#include 

"../h/systm.h" 


#include 

".../h/dir.h" 


#include 

"../h/user.h” 


tinclude 

"../h/proc.h" 


#include 

./h/buf.h" 


#include 

" . . /h/conf.h” 


V 


- . - J 


A sun 
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#include ”. 
#include 
#include ". 
#include ”. 
#include ”. 
#include ”. 
#include ’*. 
#include ”. 
#include ". 
#include ”. 
#include ". 


./h/file.h” 

/h/uio .h” 

. /h/ioctl.h” 

. /machine/mmu.h” 

. /machine/pte.h” ' 

. /sun/fbio.h” 

. /sundev/mbvar.h” 

. /pixrect/pixrect.h" 
. /pixrect/pr_util.h” 
. /pixrect/cglreg.h” 
.7 pixrect/cglvar.h” 


#if NWIN > 0 

#define CG1_0PS &cgl_ops 

struct pixrectops cgl_ops = { ^ 

cgl_rop;^ 

c g l_pu t c o 1 o rmap, 
cgl^jput attributes^ 

); 

#else 

#define CG1__0PS (struct pixrectops *j 0 
#endif 

tdefine CGISIZE (sizeof (struct cglfb)) 
struct cglpr cgoneprdatadefault = 

{ 0, 0, 255, 0, 0 In¬ 
struct pixrect cgonepixrectdefault = 

{ CG1_0PS, { CG1_WIDTH, CG1_HEIGHT }, CG1_DEPTH, /* fille4 in later */ 0 }; 


* Driver information for auto-configuration stuff. 
*/ 

int cgoneprobe(), cgoneintr(); 
struct pixrect cgonepixrect[NCGONE]; 
struct cglpr cgoneprdata[NCGONE]/ 
struct mb_device *cgoneinfo[NCGONE]; 
struct mb_driver cgonedriver = { 

cgoneprobe, 0^ 0, 0, 0, cgoneintr, 

CGISIZE, ”cgone”, cgoneinfo, 0, 0, 0, 

}; 


* Only allow opens for writing or reading and writing 

* because reading is nonsensical. 

*/ 

cgoneopen(dev, flag) 
dev_t dev; 

{ 

return(fbopen(dev, flag, NCGONE, cgoneinfo)); 

} 
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-^j^ 

* When close driver destroy pixrect. 

*/ 

/*ARGSUSED*/ 
cgoneclose(dev^ flag) 
dev__t dev; 

{ 

register int unit = minor(dev); 

if ( (caddr_t) &cgoneprdata [unit ] == cgonepixrect [unit ] .pr__data) { 
bzero((caddr_t)&cgoneprdata[unit ], sizeof (struct cglpr)); 
bzero ( (caddr__t) Scgonepixrect [unit], sizeof (struct pixrect)); 

} 

} 

/*ARGSUSED*/ 

cgoneioctl(dev^ cmd^ data^ flag) 
dev_t dev; 
caddr__t data; 

{ 

register int unit = minor(dev); 
switch (cmd) { 
case FBIOGTYPE: { 

register struct fbtype *fb = (struct fbtype *)data; 

fb“>fb__type = FBTYPE_SUN1C0L0R; 
fb->fb__height = 480; 
fb->fb_width = 640; 
f b->f b__depth =8; 
fb->fb_cmsize =256; 
fb->fb_size = 512*640; 
break; 

} 

case FBIOGPIXRECT: { 

register struct fbpixrect *fbpr = (struct fbpixrect *)data; 
register struct cglfb *cglfb = 

(struct cglfb *)cgoneinfo[(unit)]->md_addr; 

/* 

* "Allocate” and initialize pixrect data with default. 

*/ 

fbpr“>fbpr_j3ixrect = &cgonepixrect [unit'] ; 
cgonepixrect[unit] = cgonepixrectdefault; 

fbpr->fbpr_jpixrect->pr__data = (caddr__t) &cgoneprdata [unit] ; 
cgoneprdata[unit] = cgoneprdatadefault; 

/* 

* Fixup pixrect data. 

*/ 

cgoneprdata[unit].cgpr_va = cglfb; 

/* 

* Enable video 
*/ 

V___. 
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cgl_setreg{cglfb, CG_FUNCREG^ CG_VIDEOENABLE); 

/* 

* Clear interrupt 
*/ 

cgl_intclear(cglfb); 
break; 

} 

default: 

return (ENOTTY); 

} 

return (0); 

} 

/* 

* We need to handle vertical retrace interrupts here. 

* The color map(s) can only be loaded during vertical 

* retrace; we should put in ioctls for this to synchronize 

* with the interrupts. 

* FOR NOW, see comments in the code. 

*/ 

cgoneintclear(cglfb) 

struct cglfb *cglfb; 

{ 

/* 

* The Sun-1 color frame buffer doesn't indicate that an 

* interrupt is pending on itself so we don't know if the interrupt 

* is for our device. So, just turn off interrupts on the cgone board. 

* This routine can be called from any level. 

*/ 

cgl_intclear(cglfb); 

/* 

* We return 0 so that if the interrupt is for some other device 

* then that device will have a chance at it. 

*/ 

return(0); 

} 

int 

cgoneintr() 

{ 

return(fbintr(NCGONE, cgoneinfo, cgoneintclear)); 

} 

/*ARGSUSED*/ 

cgonemmap(dev, off, prot) 
dev_t dev; 
off_t off; 
int prot; 

{ 

return(fbmmap(dev, off, prot, NCGONE, cgoneinfo, CGISIZE)>; 

} 
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#include ”../sundev/cgreg.h” 

/* 

* Note: using old cgreg.h to peek and poke for now. 

*/ 

/* 

* We determine that the thing we're addressing is a color 

* board by setting it up to invert the bits we write and then writing 

* and reading back DATAl, making sure to deal with FIFOs going and coming. 
*/ 

#define DATAl 0x5C 
#define DATA2 0x33 
/*ARGSUSED*/ 
cgoneprobe (reg,^ unit) 
caddr__t reg; 
int unit; 

{ 

register caddr_t CGXBase; 
register u_char *xaddr, *yaddr; 

CGXBase = reg; 

if (pokec ( (caddr__t) GR_f reg, GR_copy__invert) ) 
return (0); 

if (pokec ( (caddr__t) GR^mask, 0)) 
return (0); 

xaddr = (u_char *) (CGXBase + GR_x_select + GR__update + GR_setO) ; 
yaddr = (u_char *) (CGXBase + GR__y_select + GR_setO) ; 
if (pokec((caddr_t)yaddr, 0)) 
return (0); 

if (pokec ( (caddr__t) xaddr, DATAl)) 
return (0); 

(void) peekc((caddr_t)xaddr); 

(void) pokec((caddr_t)xaddr, DATA2); 

if (peekc((caddr_t)xaddr) == (~DATA1 & OxFF)) { 

/* 

* The Sun-1 color frame buffer doesn't indicate that an 

* interrupt is pending on itself. 

* Also, the interrupt level is user program changable. 

* Thus, the kernel never knows what level to expect an 

* interrupt on this device and doesn't know is an interrupt 

* is pending. 

* So, we add the cgoneintr routine to a list of interrupt 

* handlers that are called if no one handles an interrupt. 

* Add__default_intr screens out multiple calls with the same 

* interrupt procedure. 

*/ 

add__default_intr (cgoneintr) ; 
return (CGISIZE); 

} 

return (0); 


#endif 


XT mlcrosyslwns 


Revision A of 9 May 1988 






/ 


82 Pixrect Rete’ence Manual 



This is how the driver is plugged into the auto-configuration mechanism, 
/etc/conf ig reads a line in the configuration file for a Sun-1 color frame 
buffer. 


/- 



device 

cgoneO at mbO csr OxecOOO priority 3 


V_ 


_ _ __ J 


An external reference to cgonedriver (line cgone.4) is made in a table main¬ 
tained by the auto-configuration mechanism. At boot time, if the auto¬ 
configuration mechanism can resolve the reference to cgonedriver then the 
contents of this stmcture are used to configure in the device: 


o cgoneprobe - The name of the probe procedure (line cgone.5). 

□ cgoneintr - The name of the intermpt procedure (line cgone.6). 

□ CGISIZE - The size in b 5 tes of the address space of the device. 

□ cgone - The prefix of the device. Used in status and error messages. 

□ cgoneinf o - The array of devices pointers of the driver’s type (line 
cgone.2). 


□ The other field’s defaults suffice for most pixel addressable devices. 

cgoneprobe is called to let the driver decide if the virtual address at reg is 
indeed a device that this driver recognizes as one of its own. The unit argu¬ 
ment is the minor device number of this device. Writing a good probe routine 
can be difficult. The trick is to use some idiosyncrasy of the device that differen¬ 
tiates it from others. The real driver for the Sun-1 color frame buffer determines 
that it is addressing a Sun-1 color frame buffer by setting it up to invert the data 
written to it and reading back the result. The details of this code are not impor¬ 
tant to this discussion and is not included. Zero is returned if the probe fails and 
CGISIZE is returned if the probe succeeds. 


cgoneintr is called when an interrupt is generated at the beginning of the 
vertical retrace. There are a variety of things that one might want to synchronize 
with such an interrupt, e.g., load the colormap or move the cursor. Currently, the 
utility fbintr simply disables the interrupt from happening again (line 
cgone.6). 


int fbintr (numdevs, inb_devs, intclear) 
int numdevs; 

struct mb_device **inb_devs; 
int (*intclear) (); 


numdevs is the maximum number of devices of these type configured. 
itib_devs is the array of devices descriptions, intclear is called back to 
actually turn off the interrupt for a particular device, intclear must have the 
same calling sequence as cgoneintclear (line cgone.7), i.e., it take the vir¬ 
tual address of the device to disable interrupts. cgl_intclear (line cgone.8) 
is a macro that actually disables the interrupts of cglfb. 
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Open 


Mmap 



When an open system call is made at the user level cgoneopen () is called. 

-^-— V 

cgoneopen(dev, flag) 
dev___t dev; 

{ 

return(fbopen(dev, flag, NCGONE, cgoneinfo)); 

} 

< _ ^ _ —) 

cgoneopen () uses the utility f bopen (). 

int fbopen(dev, flag, numdevs, inb_devs) 
dev_t dev; 

int flag, numdevs; 

struct mb^device **mb_devs; 

f bopen () checks to see if dev is available for opening. If not the error ENXIO 
is returned. If flag doesn’t ask for write position (FWRITE) then the error EIN- 
VAL is returned. Normally, zero is returned on a successful open. 

The memory map routine in a device driver is responsible for returning a single 
physical page number of a portion of a device. 

--^ 

/*ARGSUSED*/ 

cgonemmap(dev, off, prot) 
dev_t dev; 
off_t off; 
int prot; 

{ 

return(fbmmap(dev, off, prot, NCGONE, cgoneinfo, CGISIZE)) ; 

} 

k_^___ J 


cgoneinmap () used the utility f binmap (). 

int fbmmap(dev, off, prot, numdevs, mb_devs, size) 
dev__t dev; 
off__t off; 

int prot, numdevs, size; 

struct mb_device **mb_devs; 

The parameters to fbmmap () are similar to fbopen (). However, of f is the 
offset in bytes from the beginning of the device, prot is passed through but 
currently not used. 
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loctl 


A pixrect kernel device driver must respond to two input/output control requests: 



□ FBIOGTYPE — Describe the characteristics of the pixel addressable device. 


□ FBIOGPIXRECT — Hand out a pixrect that may be used in the kernel. This 
ioctl caU is made from within the kernel. This is only required of frame 
buffers. 


--^ 

#if NWIN >0 /* cgone.9*/ 

#define CGl_OPS &cgl_ops 
struct pixrectops cgl_ops = { 

^ cgl_rop^ /*cgone.l0*/ 

eg l_put c o 1 o rmap, 

}; 

#else 

#define CGl_OPS (struct pixrectops *)0 
#endif 

struct cglpr cgoneprdatadefault = 

{ 0, 0, 255, 0, 0 In¬ 
struct pixrect cgonepixrectdefault = 

{ CGl_OPS, { CG1_WIDTH, CG1_HEIGHT }, CG1_DEPTH, /* filled in later */ 0 In¬ 
struct pixrect cgonepixrect[NCGONE]; /*cgone.ll*/ 
struct cglpr cgoneprdata[NCGONE]; 

cgoneioctl(dev, cmd, data, flag) 
dev_t dev; 
caddr_t data; 

{ - 
register int unit = minor(dev); 

switch (cmd) { 
case FBIOGTYPE: { 

register struct fbtype *fb = (struct ifbtype *)data; 

fb->fb_type = FBTYPE_SUNlCOLOR; 

fb->fb_height = CG1_HEIGHT; 

fb->fb_width = CG1_WIDTH; 

fb~>fb_depth = 8; 

fb->fb_cmsize =256; 

fb->fb_size = CG1_HEIGHT*CG1_WIDTH; 

break; 

1 

case FBIOGPIXRECT: { 

register struct fbpixrect *fbpr = (struct fbpixrect *)data; 
register struct eglfb *cglfb = 

(struct eglfb *)egoneinfo[(unit)]->md_addr; 
fbpjr->fbpr_pixrect = &cgonepixrect [unit] ; /*cgone.l2*/ 
cgonepixrect[unit] = cgonepixrectdefault; /*cgone.l3*/ 

fbpr->fbpr_jpixrect->pr_data = (caddr_t) &cgoneprdata[unit];/*cgone.14*/ 
cgoneprdata[unit] = cgoneprdatadefault; /*cgone.l5*/ 
cgoneprdata[unit].cgpr_va = eglfb; /*cgone.l6*/ 

cgl_setreg(eglfb, CG_FUNCREG, CG__VIDEOENABLE); /*cgone.l7*/ 
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cgl_intclear(cglfb); 
break; 

} 


/*cgone.18*/ 


default: 

return (KNOTTY); 

} 

return (0); 


The SunView driver isn’t configured into the system when NWIN = 0 (fine 
cgone.9). When there is no SunView driver, don’t reference the pixrect opera¬ 
tions cgl_rop () and cgl_j)ut colormap (). The kernel version of 
cgl_rop {) (line cgone.lO) only needs to be able to read and write memory 
pixrects for cursor management. Thus, you can 

- ^ -- —— 

#ifndef KERNEL 

/* code not associated with reading and writing */ 

/* memory pixrects */ 

#endif KERNEL 


to reduce the size of the code. 

Memory for pixrect public (pixrect stmcture) and private (cglpr stmcture) 
objects is provided by arrays of each (line cgone.ll) NCGONE long. A device n 
in these correspond to device n in cgoneinf o. 

Lines cgone.ll through cgone. 16 initialize a pixrect for a particular device. This 
ioctl can should enable video for a frame buffer (line cgone.17) and disable 
inteiTupts as weU (line cgone.18). 


Close 


When the device is no longer being referenced, cgoneclose 0 iscaUed. AU 
that is done is that the pixrect data stmctures of the device are zeroed. 


cgoneclose(dev, flag) 
dev_t dev; 

{ 

register int unit = minor(dev); 

if ((caddr_t)Scgoneprdata[unit] == cgonepixrect[unit].pr_data) ( 
bzero((caddr_t)Scgoneprdata[unit], sizeof (struct cglpr)); 
bzero((caddr_t)Scgonepixrect[unit], sizeof (struct pixrect)); 


#endif 
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Plugging Your Driver into 
UNIX 



You need to add the device driver procedures to cde vsw in 
/sys /sun/conf. c after assigning a new major device number to your driver: 



Also, you need to add the new files associated with your driver to 
/sys/conf/files.sun: 


pixrect/cgl_colormap. c optional cgone win device-driver 
pixrect/cgl_rop. c optional cgone win device-driver 
sundev/cgone .n optional cgone device-driver 


A.7. Access Utilities This section describes utilities used by pixrect drivers. The pixrect header files 

memvar. h, pixrect. h and pr_ut il. h contain useful macros that you 
should familiarize yourself with; they are not documented here. 

pr_clip(dstp, srcp) 

struct pr_subregion *dstp; _ 

struct pr_prpos *srcp; 

pr_clip adjusts the position and size of dstp, the destination pixrect subre- 
gion, to fall within dstp->pr. If * scrp, the source pixrect position, is not 
zero then the position of the source is clipped to fall within dstp. 

Two operations on operations, pr_reversesrc 0 andpr_reversedst (), 
are provided for adjusting the operation code to take into account video reversing 
of monochrome pixrects of either the source or the destination. 


o 




These are implemented by table lookup in which the index into the tables is 
(6p»l) &0xF where op is the operation passed into pixrect public procedures. 
This process can be iterated, e.g.. 
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A.8. Rop 


A.9. Batchrop 

A.10. Vector 


Importance of Proper 
Clipping 

A. 11. Colormap 
Monochrome 


A.12. Attributes 


pr_reversedst[pr_reversesrc[op]]. 

These are the major cases to be considered with the pwo_rop () operation: 

□ Case 1 -- we are the source for the pixel rectangle operation, but not the des¬ 
tination. This is a pixel rectangle operation from the frame buffer to another 
kind of pixrecL If the destination is not memory, then we will go indirect by 
allocating a memory temporary, and then asking the destination to operate 
from there into itself. 

□ Case 2 — writing to your frame buffer. This consists of 4 different cases 
depending on where the data is coming from: from nothing, from memory, 
from some other pixrect, and from the frame buffer itself. When the source 
is some other pixrect, other than memory, ask the other pixrect to read itself 
into temporary memory to make the problem easier. 

A simple batchrop implementation could iterate on the batch items and call rop 
for each. Even in a more sophisticated implementation, while iterating on the 
batch items, you might also choose to bail out by calling rop when the source is 
skewed, or if clipping causes you to chop off in left-x direction. 

There are some notable special cases that you should consider when drawing vec¬ 
tors: 

o Handle length 1 or 2 vectors by just drawing endpoints. 

□ If vector is horizontal, use fast algorithm. 

□ If vector is vertical, use fast algorithm. 

The hard part in vector drawing is clipping, which is done against the rectangle 
of the destination quickly and with proper interpolation so that the jaggies in the 
vectors are independent of clipping. 

Each color raster device has its own way of setting and getting the colormap. 

For monochrome raster devices, when prj)ut colormap {) is called, the con¬ 
vention is that if red [ 0 ] is zero then the display is light on dark, otherwise dark 
on light. For monochrome raster devices, when pr_get colormap 0 is 
called, the convention is that if the display is light on dark then zero is stored in 
red [ 0 ], green [ 0 ] and blue [ 0 ] and -1 is stored in other positions in the 
color map. Otherwise, if the display is daik on light, then zero and -1 are 
reversed. 

pr_getattr ibutes () and pr j>utattributes () operations get or set a 
bitplane mask in color pixrects, respectively. 
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Monochrome 

A. 13. Pixel 
A. 14. Stencil 


A. 15. Polygon 


Monochrome devices ignore pr j>utattribute () calls that are setting the 
bitplane mask. Monochrome devices always return 1 when 
pr_getattribute () asking for the bitplane mask. 

pwo_get () and pwo_put () operations get or set a single pixel, respectively. 

In its most efficient implementation, stencil code parallels rop code, all the while 
considering the 2 dimensional stencil. One way to implement stencil is to use 
rops. We pay a small efficiency penalty for this. You may not consider writing 
the special purpose code worthwhile for the bitmap stencils since they probably 
won’t get used nearly as much as rop. Here’s the basic idea (Temp is a tem¬ 
porary memory pixrect): 


/- 


A 

Temp = Dest 



Temp = Dest 

op Source 


Temp = Temp 

& Stencil 


Dest = Dest 

& "'Stencil 


Dest = Dest 

i Temp 




j 


i.e.. 


/ - 



Dest = (Dest & “Stencil) | 

1 ( (Dest op Source) & Stencil) 


^ _ 




pr_polyline () is a natural extension to pr_vector (). It is especially 
useful for devices that can optimize this operation. 
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Pixrect Functions and Macros 

B.l. Making Pixrects. 

B.2. Text. 

B.3. Raster Files. 

B.4. Memory Pixrects. 

B.5. Colormaps and Bitplanes 

B.6. Rasterops... 

B.7. Double Buffering. 
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B.2. Text 



Table B-2 Text 


Name 

Function 

Compute Bounding Box 
of Text String 

pf_textbound(bound, len, font, text) ^ 
struct pr_subregion *bound; 
int len; 

Pixfont *font; 
char *text; 

Compute Location of 
Characters in Text 

String 

struct pr_size pf_textbatch(where, lengthp, font, text) 
struct prj>os where []; 
int *lengthp; 

Pixfont *font; 
char *text; 

Compute Width and 
Height of Text String 

struct pr_size pf_textwidth(len, font, text) 
int len; 

Pixfont *font; 
char *text; 

Load Font 

Pixfont *pf__open (name) 
char *name; 

Load Private Copy of 
Font 

Pixfont *pf_open_j)rivate (name) 
char *name; 

Load System Default 

Font 

Pixfont *pf_default0 

Release Pbfont 

Resources 

pf_close(pf) 

Pixfont *pf; 

Unstructured Text 

'1 

pr_text(pr, x, y, op, font, text) 

Pixrect *pr; 
int X, y, op; 

Pixfont *font; 
char *text; 


pr_ttext(pr, x, y, op, font, text) 

Pixrect *pr; 
int X, y, op; 

Pixfont *font; 
char *text; 

Write Text and 
Background 

pf_text(where, op, font, text) 
struct pr_prpos where; 
int op; 

Pixfont *font; 
char *text; 
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Table B-2 Text — Continued 


Name 

Function 

Write Text 

pf__ttext (where^ op, font, text) 


struct pr^rpos where; 


int op; 


Pixfont *font; 


char *text; 
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B.3. Raster Files 



Table B -3 Raster Files 


Name 

Function 

Initialize Raster File 
Header 

Pixrect *pr_dTamp_init (input_pr, rh, colormap, type, 
copy flag) 

Pixrect *input_pr; 
struct rasterfile *rh; 
colormap t *colormap; 
int type, copy_flag; 

Read Colormapfrom 
Raster File 

int pr_load_colormap(input, rh, colormap) 

FILE *input; 

struct rasterfile *rh; 

COlormap_t * colormap; 

Read Header from 

Raster File 

int pr_load_header(input, rh) 

FILE *input; 

struct rasterfile *rh; 

Read Image from Raster 
File 

Pixrect *pr_load_image(input, rh, colormap) 

FILE *input; 

struct rasterfile "^rh; 

COlormap_t * colormap; 

Read Raster File 

Pixrect *pr___load(input, colormap) 

FILE *input; 
colormap_t ^colormap; 

Read Standard Raster 

File 

Pixrect *pr_load_std_image(input, rh, colormap) 

FILE *input; 

struct rasterfile *rh; 

c o lo rmap__t col or map; 

Write Header to Raster 
File 

int pr_dump__header (output, rh, colormap) 

FILE ^output; 

struct rasterfile *rh; 

c o1ormap_t * co1ormap; 

Write Image Data to 
Raster File 

int pr_dump_image(pr, output, rh) 

Pixrect *pr; 

FILE ^output; 
struct rasterfile *rh; 

Write Raster File 

int pr_dump(input_pr, output, colormap, type, copy flag) 
Pixrect *input_pr; 

FILE ^output; 
colormap_t ^colormap; 
int type, copy__flag; 



o 
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K _ B.4. Memory Pixrects 


Table B-4 Memory Pixrects 


Name 

Function 

Create Memory Pixrect 
from an Image 

Pixrect *mem_point(width, height, depth, data) 
int width, height, depth; 
short *data; 

Create Memory Pixrect 

Pixrect *mein_create (w, h, depth) 
int w, h, depth; 

Create Static Memory 
Pixrect 

fdefine mpr static(name, w, h, depth, image) 
int w, h, depth; 
short *image; 

Get Memory Pixrect 

Data Bytes per Line 

#define mpr_linebytes(width, depth) 

( ( (pr_product (width, depth)+15) »3) &~1) 

Get Pointer to Memory 
Pixrect Data 

#define mpr_d(pr) 

((struct mpr_data *)(pr)->pr_data) 



Variations for the Sun386i: 

□ inem_point {) on the Sun386i does not flip the bitmap pointed to by *data. The pixrect structure returned 
does not have the MP_STATIC or the MP_I38 6 flag set. 

o mem_creat e () on the Sun386i creates an empty pixrect with the MP_I3 8 6 flag set. 

□ mpr_static () on the Sun386i creates a pixrect with both the MP_I38 6 and mp_STATIC flags set. 


c 
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B.5. Colormaps and Bitplanes 


Table B-5 Colormaps and Bitplanes 


Name 

Function 

Exchange Foreground 

pr_reversevideo(pr, min, max) 

and Background Colors 

Pixrect *pr; 
int min, max; 

Get Colormap Entries 

tdefine pr_getcolormap(pr, index, count, red, green, 
blue) 

Pixrect *pr; 
int index, county- 

unsigned char red[], green[], blue[]; 

Get Plane Mask 

#define pr_getattributes(pr, planes) 

Pixrect *pr; 
int *planes; 

Set Background and 

pr blackonwhite(pr, min, max) 

Foreground Colors 

Pixrect *pr; ^ 

int min, max; 

Set Colormap Entries 

tdefine prjputcolormap(pr, index, count, red, green, 
blue) 

Pixrect *pr; 
int index, county- 

unsigned char red[], green[], blue[]; 

Set Foreground and 

pr__whiteonblack (pr, min, max) 

Background Colors 

Pixrect ^pr; 
int min, max; 

Set Plane Mask 

tdefine pr_putattributes(pr, planes) 

Pixrect *pr; 
int *planeSy- 

Subregion Get 

#define prs___getcolormap (pr, index, count, red, green. 

Colormap Entries 

blue) 

Pixrect *pr; 
int index, county- 

unsigned char red[], green[], blue[]; 

Subregion Get Plane 

#define prs_getattributes(pr, planes) 

Mask 

Pixrect ^pr; 
int *planes; 

Subregion Set 

#define prs_putcolormap(pr, index, count, red, green. 

Colormap Entries 

blue) 


Pixrect *pr; 
int index, county- 

unsigned char red[], green[], blue[]; 
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Table B-5 Colormaps and Bitplanes — Continued 


Name 

Function 

Subregion Set Plane 

fdefine prs_putattributes(pr^ planes) 

Mask 

Pixrect *pr; 


int *planes; 
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B.6. Rasterops 


Table B-6 Rasterops 


Name 


Draw Textured or Solid 
Lines with Width 


Draw Textured Polygon 


Draw Vector 


Get Pixel Value 


Masked RasterOp 


Multiple RasterOp 


RasterOp 


Replicated Source 
RasterOp 

Set Pixel Value 


Function 


tdefine pr_line(pr, xO, yO, xl, yl, brush, tex, op) 

Pixrect *pt; 

int xO, yO, xl, yl; 

struct pr_brush *brush; 

struct pr_texture *tex; 

int op; 

pr_polygon_2 (dpr, dx, dy, nbnds, npts, vlist, op, 
spr, sx, sy) 

Pixrect *dpr, *spr; 
int dx, dy 
int nbnds, npts[]; 
struct pr_pos *vlist; 
int op, sx, sy; 

tdefine pr_vector(pr, xO, yO, xl, yl, op, value) 
Pixrect *pr; 

int xO, yO, xl, yl, op, value; 

tdefine pr_get(pr, x, y) 

Pixrect *pr; 
int X, y; 

tdefine pr_stencil(dpr, dx, dy, dw, dh, op, 
stpr, stx, sty, spr, sx, sy) 

Pixrect *dpr, *stpr, *spr; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 

tdefine pr_batchrop(dpr, dx, dy, op, items, n) 

Pixrect *dpr; 

int dx, dy, op, n; 

struct pr_j)rpos items [ ] ; 

tdefine pr_rop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 

pr_replrop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 

tdefine pr_put(pr, x, y, value) 

Pixrect *pr; 
int X, y, value; 


XT microsystems 
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Table B-6 Raster ops — Continued 


Name 

Function 

Subregion Draw Vector 

#define prs_vector(pr, posO, posl^ op^ value) 

Pixrect *pr; 

struct prj)OS posO^ posl; 
int op;. value; 

Subregion Get Pixel 

Value 

#define prs get(srcprpos) 
struct prj>rpos srcprpos; 

Subregion Masked 
RasterOp 

#define prs stencil(dstregion^ op, stenprpos, srcprpos) 
struct pr___subregion dstregion; 
int op; 

struct pr__prpos stenprpos, srcprpos; 

Subregion Multiple 
RasterOp 

fdefine prs batchrop(dstpos, op, items, n) 
struct pr__prpos dstpos; 
int op, n; 

struct pr j)rpos items [] ; 

Subregion RasterOp 

#define prs_rop(dstregion, op, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr_jprpos srcprpos; 

Subregion Replicated 
Source RasterOp 

#define prs_replrop(dsubreg, op, sprpos) 
struct pr subregion dsubreg; 
struct pr_prpos sprpos; 

Subregion Set Pixel 

Value 

#define prs_put(dstprpos, value) 
struct prj>rpos dstprpos; 
int value; 

Trapezon RasterOp 

pr_traprop(dpr, dx, dy, t, op, spr, sx, sy) 

Pixrect *dpr, *spr; 
struct pr_trap t; 
int dx, dy, sx, sy op; 
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B.7. Double Buffering 


Table B-7 Double Buffering 


Name 

Function 

Get Double Buffering 

pr_dbl_get(pr, attribute) 

Attributes 

Pixrect "^pr; 


int attribute; 

Set Double Buffering 

pr_dbl_set(pr, attribute list) 

Attributes 

Pixrect *pr; 


int *attribute_list; 
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Name 


Brush 


Character Descriptor 


Data Structure 


typedef struct pr_brush { 
int width; 

} Pr_brush; 

struct pixchar { 

struct pixrect *pc_pr; 
struct prj>os pc_home; 
struct pr_pos pc_adv; 


Font Descriptor 


Pixrect 


typedef struct pixfont { 

struct pr_size pf_defaultsize; 
struct pixchar pf_char[256]; 

} Pixfont; 

typedef struct pixrect { 

struct pixrectops *pr_ops; 
struct pr__size pr_size; 
int pr_depth; 
caddr_t pr_data; 

} Pixrect; 


sun 
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Table C-1 Pixrect Data Structures — Continued 


Name 


Data Structure 


Pixrect Operations struct pixrectops { 

int (*pro_rop)(); 

int (*pro_stencil)(); 

int (*pro_batchrop)(); 

int (*pro_nop)(); 

int (*pro_destroy)(); 

int (*pro_get)(); 

int (*pro_put)(); 

int (*pro_vector)(); 

struct pixrect *{*pro_region)(); 

int (*pro_putcolormap)(); 

int (*pro_getcolormap) O; 

int {*pro_j5utattributes) 0 ; 

int (*pro_getattributes) 0; 


Position 


struct pr_pos { 
int X, y; 

}; 


Position Within a 
Pixrect 


Size 


Subregion 


struct pr_prpos { 

struct pixrect *pr; 
struct pr_pos pos; 

In¬ 
struct pr_size { 
int X, y; 

In¬ 
struct pr_subregion { 
struct pixrect *pr; 
struct prj)OS pos; 
struct pr_size size; 
In- 
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Table C-1 Pixrect Data Structures — Continued 


Name 


Texture 


Trapezon 


Data Structure 


typedef struct pr__texture { 
short ^pattern; 
short offset; 

struct pr_texture_options { 
unsigned startpoint : 1, 
endpoint : 1, 
balanced : 
givenpattern : 
res_fat : 1, 
resj>oly: 
res__mvlist : 1, 
res_right : 1, 
res_close : 1; 

} options; 
short res_polyoff; 
short res__oldpatln; 
short res__fatoff; 

} Pr_texture; 

struct pr_trap { 

struct pr_fall *left, *right; 
int yO, yl; 


Trapezon Chain 


struct pr_chain { 

struct pr__chain *next; 
struct pr__size size; 
int *bits; 


Trapezon Fall 


struct pr_fall { 

struct prj>os pos; 
struct pr_chain *chain; 
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Curved Shapes 


This appendix describes pr_traprop (), a function for rendering curved 
shapes with Pixrm. pr_traprop() is an advanced pixrect operation analo¬ 
gous to pr_rop (). 

The curve to be rendered must first be stored in a data structure called pr_trap 
which is based on a region called a trapezon, rather than on a rectangle. A tra- 
pezon is a region with an irregular boundary. Like a rectangle, a trapezon has 
four sides: top, bottom, left, and right. The top and bottom sides of a trapezon 
are sticught and horizontal. A trapezon differs from a rectangle in that its left and 
right sides are irregular curves, called falls, rather than straight lines. 

A fall is a line of irregular shape. Vertically, a fall may only move downward. 
Horizontally, a fall may move to the left or to the right, and this horizontal 
motion may reverse itself. A fall may also sustain pure horizontal motion, that 
is, horizontal motion with no vertical motion. 

The figures below show a typical trapezon with source and destination pixrects, 
and some examples of filled regions that were drawn by pr_traprop (). 

Figure D-1 Typical Trapezon 


destination source 

pixrect pixrect 
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Figure D-2 Some Figures Drawn by pr_trapr op () 




pr_traprop (dpr,^ dx^ dy,^ t, op^ spr^ sx^ sy) 
struct pixrect *dpr^ *spr; 
struct pr_trap t; 
int dx^ dy^ sx, sy op; 

dpr and spr are pointers to the destination and source pixrects, respectively, t 
is the trapezon to be used, dx and dy specify an offset into the destination pix¬ 
rect. sx and sy specify an offset into the source pixrect. op is an op-code as 
specified previously (see Section 3.3, The Op Argument). 


struct pr_trap { 

struct pr_fall *left^ *righ 
int yO, yl; 


struct pr_fall { 

struct pr_pos pos; 
struct pr_chain *chain 


struct pr_chain { 

struct pr__chain *next; 
struct pr_size size; 
int *bits; 


pr_traprop () performs a rasterop from the source to the destination, clipped 
to the trapezon’s boundaries. A program must call pr_t rapr op () once per 
trapezon; therefore this procedure must be called at least twice to draw the letter 
A in Figure D-2. 

The source pixrect is aligned with the destination pixrect; the pixel at (sx, sy) in 
the source pixrect goes to the pixel at (dx, dy) in the destination pixrect (see 
Figure D-2). 

Positions within the trapezon are relative to position (dx, dy) in the destination 
pixrect Thus, a position defined as (0,0) in the trapezon would actually be at 
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(dx, dy) in the destination pixrect. 

The stracture pr_trap defines the boundaries of a trapezon. A trapezon con¬ 
sists of pointers to two falls (left and right) and two y coordinates specify¬ 
ing the top and bottom of the trapezon (yO and yl). Note that the trapezon’s top 
and bottom may be of zero width; yO and yl may simply serve as points of 
reference. 

Each faU consists of a starting position (pos) and a pointer to the head of the list 
of chains describing the path the faU is to take (chain). A faU may start any¬ 
where above the trapezon and end anywhere below it. pr_traprop() ignores 
the portions of a faU that lie above and below the trapezon. If a faU is shorter 
than the trapezon, pr_traprop () wiU clip the trapezon horizontaUy to the 
endpoint of the faU in question. Figure D-3 illustrates the way this works. 

A chain is a member of a linked Ust of stractures that describes the movement 
of the faU. Each chain describes a single segment of the faU. Each chain consists 
of a pointer to the next member of the chain (next), the size of the bounding 
box for the chain (size), and a pointer to a bit vector containing motion com¬ 
mands (bits). 

Each chain may specify motion to the right and/or down, or motion to the left 
and/or down; however, a single chain may not specify both rightward and left¬ 
ward motioa Remember that motion may not proceed upward, and that straight 
horizontal motion is permitted. 

The X value of the chain’s size determines the direction of the motion; a posi¬ 
tive X value indicates rightward motion, while a negative x value indicates left¬ 
ward motion. The y value of the chain’s size must always be positive, since a 
faU may not move upward (in the direction of negative y). 

A chain’s bit vector is a command string that teUs pr_traprop () how to draw 
each segment of the faU. Each set (1) bit in the vector is a command to move one 
pixel horizontaUy and each clear (0) bit is a command to move one pixel verti- 
caUy. The bits within the bit vector are stored in b 5 d;e order, from most 
significant bit to least significant bit This ordering corresponds to the left-to- 
right ordering of pixels within a memory pixrect. 

The faU begins at the starting position specified in pr_f all. The motion 
proceeds downward as specified in the first bit vector in the chain, from the 
high-order bit to the low-order bit. When the fall reaches the bottom of the 
bounding box, it continues at the top of the next chain’s bounding box. Note that 
the faU wiU always begin and end at diagonaUy opposite comers of a given 
bounding box. 

If a bit vector specifies a segment of the faU that would run outside of the bound¬ 
ing box, pr_traprop () cUps that segment of the faU to the bounding box. 

TThis would occur when the sum of the 1 ’s in a chain’s bit vector exceeds the 
chain’s x size, or when the sum of the O’s in the chain’s bit vector exceeds the 
chain’s y size. Wten this happens, the segment in question runs along the edge 
of the bounding box until it reaches the comer of the bounding box diagonaUy 
opposite to the comer in which it started. 
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If the fan has a straight vertical segment, the x size of its chain must be 0. If the 
fan has a straight horizontal segment, the y size of its chain must be 0. 


Figure D-3 


Trapezon with Clipped Falls 



The fonowing program draws an octagon. 



Revision A of 9 May 1988 


Appendix D — Curved Shapes 113 



Figure D-4 Example Program using pr_t r apr op () 


#includ.e <pixrect/pixrect_hs .h> 

int shallowsteep [] = {Oxbbbbbbbb,^ Oxbbbbbbbb, 

0x44444444^ 0x44444444}; 

int steepshallow[] = {0x44444444, 0x44444444, 

Oxbbbbbbbb, Oxbbbbbbbb}; 

struct pr_chain leftl = {0, {64, 64}, steepshallow}, 

leftO = {Sleftl, {-64, 64}, shallowsteep}, 
rightl = {0, (-64, 64}, steepshallow}, 
righto = {&rightl, {64, 64}, shallowsteep}; 

struct pr_fall left_oct = {{0, 0}, &left0}, 
right_oct = {{0, 0}, &right0}; 

struct pr__trap octagon = {&left_oct, &right_oct, 0, 128}; 

mainO 

{ 

Pixrect *screen; 

screen = pr_open(”/dev/fb"); 

pr_traprop(screen, 576, 450, octagon, PIX_SET, 0,0,0); 
pr_close(screen); 


pr_chain specifies the left lower, the left upper, the right lower, and the right 
upper sides of the octagon, in that order. pr_f all specifies first the left side, 
then the right side of the octagon. 

Each of the eight sides of the octagon is half a chain. The two upper left sides 
correspond to chain left 0. The bits start out with mostly 1 ’s (Oxb is binary 
1011) for the shallow uppermost left edge. They turn to mostly O’s (0x4 is 
binary 0100) for the next edge down, which is steeper. 
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Index 


Special Characters 
<rasterfile.h>, 59 
<st.dio .h>, 59 

8 

80386, see Svin386i 


B 

bitmap, 4 

bitmapped display, 4 
boolean, 4 




c 

clip pixrect, 21 

compiling pixrect programs, 6 

compute bounding box of text string, 46, 92 

compute location of characters in text string, 46,92 

compute width and height of text string, 46, 92 

convert 680X0 pixrect to Sun386i pixrect, 91 

coordinate system, 4 

create memory pixrect, 53, 95 

create memory pixrect from an image, 53, 95 

create pixrect, 22,91 

create secondary pixrect, 23, 91 

create static memory pixrect, 54, 95 

curved shapes, 109 


D 

determine supported plane groups, 37 

draw multiple points, 34 

draw textured or solid lines with width, 31, 98 

draw textured or solid polylines with width, 33 

draw textured polygon, 28, 98 

draw vector, 28, 98 


E 

exchange foreground and background colors, 35, 96 

F 

fbintr (), 82 
f bmmap (), 83 
fbopen(),83 
font 

pixrect, 28,43,45,46 
fontedit, 44 


G 

get colormap entries, 34, 96 

get current plane group, 37 

get double buffering attributes, 38,100 

get memory pixrect data bytes per line, 52,95 

get pixel value, 24,98 

gel plane mask, 36,96 

get pointer to memory pixrect data, 52, 95 

H 

header files 

pixrect, 6,7 

I 

include files 
pixrect, 6,7 

initialize raster file header, 65, 94 

L 

lint 

pixrect, 7 
load font, 44, 92 
load private copy of font, 45, 92 
load system default font, 45,92 

M 

masked RasterOp, 25,98 
mem_creat:e (), 53,95 
mem_point (), 53, 95 
memory pixrects, 6, 13, 51,53 
mpr_d (), 52, 95 
mpr_data, 51 
mpr_linebytes (), 52,95 
mpr_static (), 54, 95 
multiide RasterOp, 27,98 

o 

object-oriented programming, 5 

P 

pf_close (), 45,92 
pf_default (), 45,92 
pf_open 0,44, 92 
pf_open_private <), 45,92 
pf__text: 0,45, 92 
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pf_t ext batch (>, 46, 92 
pf_t ext bound (), 46, 92 
pf_textwidth (), 46, 92 
pf_ttext (), 45, 92 
PIX_CLR, 20 
PIX__DONTCLIP. 19. 21 
PIX_DST, 20 
PIX_ERR, 19 
PIX_N0T, 20 
PIX_SET, 20 
PIX_SRC, 20 
pixchar, 43, 103 
pixel, 51 

address, 4, 51, 55 
color, 4 

depth, 4, 51,55 
Pixf ont, 43, 103 
Pixrect, 103 
pixrect 

available plane groups, 37 
bit flipping, 13 
bitmap, 4 
bitplane, 36 
clipping, 21, 86 
close a font, 45 
compiling, 6 
coordinate system, 4 
creation of, 22 

data structures, 7.13,18,32.43. 51, 63.71, 73. 74, 75.78, 84. 

103, no 
destruction of, 24 
draw lines in, 31 
draw textured polygon in, 28 
draw vector in, 28 
eiTors, 19 

find character positions, 46 

font, 28,43,45,46 

foreground and backgroimd, 35 

get colormap, 34 

get current plane group, 37 

get double buffering, 38 

get pixel of, 24 

get plane mask, 36 

header files, 6, 7 

internals, 18,43,51, 63 

lint libraiy, 7 

load a font, 44 

load a private font, 45 

load default font, 45 

masked RasterOp, 25 

memory pixrects, 6,13, 51,53, 54 

multiple RasieiOp, 27 

object, 5 

pixel, 4 

polylines, 33 

polypoints, 34 

portability, 13 

primary, 5 

raster files, 60, 62,64, 65, 66 
RasterOp, 4, 25 
replicating, 26 
screen parameters, 22 


pixrect, continued 
secondary, 6,23 
set colormap; 35 
set double buffering, 39 
set pixel, 24 
set plane group, 38 
set plane mask, 36 
string width, 46 
text bounding box, 46 
trapezon, 109 
write text, 45,46 

writing device drivers, 69,74, 76, 83, 86 
pixrect lint libraiy, 7 
pixrect header files 

<pixrect/pixrect-h>, 6 
<pixrect/prj>lanegroups.h>, 37 
<pixrect>, 7 
<stdio.h>, 59 
pixrect macros 

MP_DISPLAY, 51 
MP_I386,51 
MP_REVERSEVIDEO, 51 
MP_STATIC, 51 
mpr_d (), 52 
mpr_linebytes(), 52 
PIX_DONTCLIP, 19. 21 
PIX_DST, 20 
PIX__ERR, 19 
PIX_NOT, 20 
PIX_SRC, 20 
PIXPG__8BIT_COLOR. 37 
PIXPG_CURRENT, 37 
PIXPG_MONO, 37 
P IXPG_OVERLAY. 37 
PIXPG_OVERLAY_ENABLE, 37 
pixrectops, 18,103 
pr_available_plane_groups (), 37 
pr_batchrop (), 27, 98 
pr_blackonwhite (), 35, 96 
pr_brush, 103 
pr_brush (), 31,33 
pr_chain, 103,110 
pr_clip 0,86 
pr_close (), 24,91 
pr_dbl__get (), 38, 100 
pr_dbl_set (), 39, 100 
pr_dest roy (), 24,91 
pr_dump (), 60, 94 
pr_dump_header (), 64, 94 
pr_dump_image (), 65, 94 
pr_dump_init (), 65, 94 
pr_fall. 103,110 
pr^flipO, 13.91 
pr_get {), 24, 98 
pr_get_plane_group 0,37 
pr_getattributes (), 36, 96 
pr__getcoldrinap <), 34, 96 
pr_line {), 31, 98 
preload0,62, 94 
pr_load_colorinap (), 66, 94 
pr_load_header (), 65,94 
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pr_load__image (), 66, 94 

pr_load_std_iniage (), 66, 94 

pr_niakef romf d (), 74 

pr_open (), 22, 91 

pr_j>olygon_2 (), 28, 98 

pr_j>olyline (), 33 

pr j>olypoint (>, 34 

pr_pos, 103 

pr_jprpos, 103 

pr_put (), 24, 98 

pr_putatt ribut Gs (), 36, 96 

pr j>ut:colormap (), 35,96 

pr_region (), 23,91 

pr__replrop (), 26, 98 

pr_rever sedst (), 86 

pr__reversesrc (), 86 

pr__reversevideo (), 35, 96 

pr_rop (), 25, 98 

pr_set_plane_group (), 38 

preset j)lanes (), 38 

pr_size, 103 

pr_stencil (), 25, 98 

pr_sub region, 103 

pretext (), 46, 92 

Pr^texture, 103 

pr^texture (), 31,33 

pr_trap, 103, 110 

pr_traprop (), 98,109 

pr_ttext (), 46, 92 

pr_unmakef romf d (), 76 

pr_vector (), 28,98 

pr_whiteonblack (), 35, 96 

primary pixrect, 5, 23 

prs__batchrop (), see pr_batchrop 

pr s_de St roy (>, see pr_de stroy 

pr s_get (), see pr_get 

prs_getattributes {),see pr_get at tributes 
prs^getcolormap (), see pr_getcolormap 
pr s__put (), see pr_j5ut 

prs j)utattributes (), see pr_j>ut at tributes 
prs_putcolormap (), see pr^utcolormap 
pr s_region 0, .yee pr_region 
pr s_repl rop (), see pr_repl rop 
prs_rop(),pr_rop 
prs_stencil (), see pr_stencil 
prs__vector (), see pr_vector 


RasterOp, 4,25,98 
read colormap from raster file, 66,94 
read header from raster file, 65, 94 
read image from raster file, 66,94 
read raster file, 62,94 
read standard raster file, 66,94 
release pixfont resources, 45,92 
release pixrect resources, 24,91 
replicated source RasterOp, 26, 98 
run-length encoding, 59 

s 

secondary pixrect, 6,23 

set background and foreground colors, 35, 96 

set colormap entries, 35,96 

set double buffering, 39,100 

set foreground and background colors, 35, 96 

set pixel value, 24, 98 

set plane group and mask, 38 

set plane mask, 36, 96 

subregion 

creation of secondary pixrect, 23, 91 
destruction of pixrect, 24, 91 
draw vector in pixrect, 28, 98 
get colormap, 34,96 
get pixel of pixrect, 24, 98 
get plane mask, 36,96 
masked RasteiOp, 25,98 
multiple RasterOp, 27,98 
RasterOp, 25, 98 
replicating, 26, 98 
set colormap, 35,96 
set pixel of pixrect, 24, 98 
set plane mask, 36, 96 
Sun386i 

pixrect, 91 

pixrect portability. 13 
pr_flip(), 13 

T 

trapezon RasterOp, 98,109 

u 

unstructured text, 46, 92 

V 

vector display, 4 
vertical retrace, 38 


R 

raster file 

data structure, 63 
initialize header, 65, 94 
read, 62, 66,94 
read colormap, 66, 94 
read header, 65, 94 
read image, 66, 94 
write, 60, 94 
write header, 64,94 
write image, 65,94 
raster file, 63 


w 

write header to raster file, 64,94 

write image data to raster file, 65,94 

write raster file, 60,94 

write text, 45,92 

write text and background, 45, 92 
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